fscanf, scanf, sscanf, vfscanf - scan formatted input
int fscanf(FILE *f, char *format, ...);
int scanf(char *format, ... );
int sscanf(char *s, char *format, ...);
int vfscanf(FILE *stream, char *format, char *args);
Fscanf reads from the named input stream f (see fopen(2)) under control of the string
pointed to by format that specifies the admissible input sequences and how they are to be
converted for assignment, using subsequent arguments as pointers to the objects to receive
the converted input. If there are insufficient arguments for the format, the behavior is
undefined. If the format is exhausted while arguments remain, the excess arguments are
evaluated (as always) but are otherwise ignored.
Scanf and sscanf are the same, but they read from stdin and the character string s,
respectively. Vfscanf is like scanf, except the args argument is a pointer to an argument
in an argument list of the calling function and the effect is as if the calling function's
argument list from that point on is passed to the scanf routines.
The format is composed of zero or more directives: one or more white-space characters; an
ordinary character (not %); or a conversion specification. Each conversion specification
is introduced by the character %. After the %, the following appear in sequence:
An optional assignment-suppressing character *.
An optional decimal integer that specifies the maximum field width.
An optional h, l (ell) or L indicating the size of the receiving object. The con-
version specifiers d, i, and n shall be preceded by h if the corresponding argument
is a pointer to short rather than a pointer to int, or by l if it is a pointer to
long. Similarly, the conversion specifiers o, u, and x shall be preceded by h if
the corresponding argument is a pointer to unsigned short rather than a pointer to
unsigned, or by l if it is a pointer to unsigned long. Finally, the conversion
specifiers e, f, and g shall be preceded by l if the corresponding argument is a
pointer to double rather than a pointer to float, or by L if it is a pointer to
long double. If an h, l, or L appears with any other conversion specifier, the
behavior is undefined.
A character that specifies the type of conversion to be applied. The valid conver-
sion specifiers are described below.
Fscanf executes each directive of the format in turn. If a directive fails, as detailed
below, fscanf returns. Failures are described as input failures (due to the unavailabil-
ity of input), or matching failures (due to inappropriate input).
A directive composed of white space is executed by reading input up to the first non-
white-space character (which remains unread), or until no more characters can be read.
A directive that is an ordinary character is executed by reading the next character from
the stream. If if differs from the one comprising the directive, the directive fails, and
the differing and subsequent characters remain unread.
A directive that is a conversion specification defines a set of matching input sequences,
as described below for each specifier. A conversion specification is executed in the fol-
Input white-space characters (as specified by isspace, see ctype(2)) are skipped, unless
the specification includes a [, c, or n specifier.
An input item is read from the stream, unless the specification includes an n specifier.
An input item is defined as the longest sequence of input characters (up to any specified
maximum field width) which is an initial subsequence of a matching sequence. The first
character, if any, after the input item remains unread. If the length of the input item
is zero, the execution of the directive fails: this condition is a matching failure,
unless an error prevented input from the stream, in which case it is an input failure.
Except in the case of a % specifier, the input item (or, in the case of a %n directive,
the count of input characters) is converted to a type appropriate to the conversion speci-
fier. If the input item is not a matching sequence, the execution of the directive fails:
this condition is a matching failure. Unless assignment suppression was indicated by a *,
the result of the conversion is placed in the object pointed to by the first argument fol-
lowing the format argument that has not already received a conversion result. If this
object does not have an appropriate type, or if the result of the conversion cannot be
represented in the space provided, the behavior is undefined.
The following conversion specifiers are valid:
d Matches an optionally signed decimal integer, whose format is the same as expected
for the subject sequence of the strtol (see atof(2)) function with 10 for the base
argument. The corresponding argument shall be a pointer to int.
i Matches an optionally signed decimal integer, whose format is the same as expected
for the subject sequence of the strtol function with 0 for the base argument. The
corresponding argument shall be a pointer to int.
o Matches an optionally signed octal integer, whose format is the same as expected for
the subject sequence of the strtoul (see atof(2)) function with 8 for the base argu-
ment. The corresponding argument shall be a pointer to unsigned int.
u Matches an optionally signed decimal integer, whose format is the same as expected
for the subject sequence of the strtoul function with 10 for the base argument. The
corresponding argument shall be a pointer to unsigned int.
x Matches an optionally signed hexadecimal integer, whose format is the same as
expected for the subject sequence of the strtoul function with 16 for the base argu-
ment. The corresponding argument shall be a pointer to unsigned int.
e,f,g Matches an optionally signed floating-point number, whose format is the same as
expected for the subject string of the strtod (see atof(2)) function. The corre-
sponding argument shall be a pointer to float.
s Matches a sequence of non-white-space characters. The corresponding argument shall
be a pointer to the initial character of an array large enough to accept the
sequence and a terminating NUL (0) character, which will be added automatically.
[ Matches a nonempty sequence of characters from a set of expected characters (the
scanset). The corresponding argument shall be a pointer to the initial character of
an array large enough to accept the sequence and a terminating NUL character, which
will be added automatically. The conversion specifier includes all subsequent char-
acters in the format string, up to and including the matching right brace (]). The
characters between the brackets (the scanlist) comprise the scanset, unless the
character after the left bracket is a circumflex (^), in which case the scanset con-
tains all characters that do not appear in the scanlist between the circumflex and
the right bracket. As a special case, if the conversion specifier begins with  or
[^], the right bracket character is in the scanlist and the next right bracket char-
acter is the matching right bracket that ends the specification. If a - character
is in the scanlist and is not the first, nor the second where the first character is
a ^, nor the last character, the behavior is implementation-defined (in Plan 9: the
scanlist includes all characters in the ASCII (sic) range between the two characters
on either side of the -).
c Matches a sequence of characters of the number specified by the field width (1 if no
field width is present in the directive). The corresponding argument shall be a
pointer to the initial character of an array large enough to accept the sequence.
No NUL character is added.
P Matches an implementation-defined set of sequences, which should be the same as the
set of sequences that may be produced by the %P conversion of the fprintf(2) func-
tion (in Plan 9, a hexadecimal number). The corresponding argument shall be a
pointer to a pointer to void. The interpretation of the input item is implementa-
tion defined; however, for any input item other than a value converted earlier dur-
ing the same program execution, the behavior of the %P conversion is undefined.
n No input is consumed. The corresponding argument shall be a pointer to integer into
which is written the number of characters read from the input stream so far by this
call to fscanf. Execution of a %n directive does not increment the assignment count
returned at the completion of fscanf.
% Matches a single %; no conversion or assignment occurs. The complete conversion
specification shall be %%.
If a conversion specification is invalid, the behavior is undefined.
The conversion specifiers E, G, and X are also valid and behave the same as, respectively,
e, g, and x.
If end-of-file is encountered during input, conversion is terminated. If end-of-file
occurs before any characters matching the current directive have been read (other than
leading white space, where permitted), execution of the current directive terminates with
an input failure; otherwise, unless execution of the current directive is terminated with
a matching failure, execution of the following directive (if any) is terminated with an
If conversion terminates on a conflicting input character, the offending input character
is left unread in the input stream. Trailing white space (including newline characters)
is left unread unless matched by a directive. The success of literal matches and sup-
pressed assignments is not directly determinable other than via the %n directive.
The return value from fscanf is the number of input items assigned, which can be fewer
than provided for, or even zero, in the event of an early matching failure. However, if
an input failure occurs before any conversion, EOF is returned.
Does not know about UTF.