int vfscanf(FILE *__stream, const char *__fmt, va_list __ap)
Formatted input. This function is the heart of the scanf family of functions.
Characters are read from stream and processed in a way described by fmt. Conversion results will be assigned to the parameters passed via ap.
The format string fmt is scanned for conversion specifications. Anything that doesn't comprise a conversion specification is taken as text that is matched literally against the input. White space in the format string will match any white space in the data (including none), all other characters match only itself. Processing is aborted as soon as the data and format string no longer match, or there is an error or end-of-file condition on stream.
Most conversions skip leading white space before starting the actual conversion.
Conversions are introduced with the character %. Possible options can follow the %:
a * indicating that the conversion should be
performed but the conversion result is to be discarded; no parameters will be
processed from ap,
the character h indicating that the argument
is a pointer to short int (rather than
int),
the 2 characters hh indicating that the
argument is a pointer to char (rather than
int).
the character l indicating that the argument
is a pointer to long int (rather than
int, for integer type conversions), or a
pointer to double (for floating point
conversions),
In addition, a maximal field width may be specified as a nonzero positive decimal
integer, which will restrict the conversion to at most this many characters from the
input stream. This field width is limited to at most 255 characters which is also the
default value (except for the c conversion that
defaults to 1).
The following conversion flags are supported:
% Matches a literal
% character. This is not a conversion.
d Matches an optionally signed decimal
integer; the next pointer must be a pointer to
int.
i Matches an optionally signed integer; the
next pointer must be a pointer to int. The
integer is read in base 16 if it begins with 0x or 0X,
in base 8 if it begins with 0, and in base 10 otherwise. Only
characters that correspond to the base are used.
o Matches an octal integer; the next pointer
must be a pointer to unsigned int.
u Matches an optionally signed decimal
integer; the next pointer must be a pointer to unsigned
int.
x Matches an optionally signed hexadecimal
integer; the next pointer must be a pointer to unsigned
int.
f Matches an optionally signed floating-point
number; the next pointer must be a pointer to
float.
e, g, F, E, G Equivalent to
f.
s Matches a sequence of non-white-space
characters; the next pointer must be a pointer to
char, and the array must be large enough to
accept all the sequence and the terminating NUL
character. The input string stops at white space or at the maximum field width,
whichever occurs first.
c Matches a sequence of width count
characters (default 1); the next pointer must be a pointer to
char, and there must be enough room for all the
characters (no terminating NUL is added). The
usual skip of leading white space is suppressed. To skip white space first, use an
explicit space in the format.
[ Matches a nonempty sequence of characters from the
specified set of accepted characters; the next pointer must be a pointer to
char, and there must be enough room for all the
characters in the string, plus a terminating NUL
character. The usual skip of leading white space is suppressed. The string is to
be made up of characters in (or not in) a particular set; the set is defined by
the characters between the open bracket [ character and a close
bracket ] character. The set excludes those characters if the
first character after the open bracket is a circumflex
^. To include a close bracket in the set, make
it the first character after the open bracket or the circumflex; any other
position will end the set. The hyphen character -
is also special; when placed between two other characters, it adds all intervening
characters to the set. To include a hyphen, make it the last character before the
final close bracket. For instance, [^]0-9-] means
the set of everything except close bracket, zero through nine, and
hyphen. The string ends with the appearance of a character not in the
(or, with a circumflex, in) set or when the field width runs out. Note that usage
of this conversion enlarges the stack expense.
p Matches a pointer value (as printed by
p in printf()); the next pointer must be a pointer to
void.
n Nothing is expected; instead, the number of
characters consumed thus far from the input is stored through the next pointer,
which must be a pointer to int. This is not a
conversion, although it can be suppressed with the
* flag.
These functions return the number of input items assigned, which can be fewer than
provided for, or even zero, in the event of a matching failure. Zero indicates that,
while there was input available, no conversions were assigned; typically this is due to
an invalid input character, such as an alphabetic character for a
d conversion. The value
EOF is returned if an input failure occurs before any
conversion such as an end-of-file occurs. If an error or end-of-file occurs after
conversion has begun, the number of conversions which were successfully completed is
returned.
By default, all the conversions described above are available except the
floating-point conversions and the width is limited to 255 characters. The float-point
conversion will be available in the extended version provided by the library
libscanf_flt.a. Also in this case the width is not
limited (exactly, it is limited to 65535 characters). To link a program against the
extended version, use the following compiler flags in the link stage:
-Wl,-u,vfscanf -lscanf_flt -lm
A third version is available for environments that are tight on space. In addition
to the restrictions of the standard one, this version implements no
%[ specification. This version is provided in the
library libscanf_min.a, and can be requested using the
following options in the link stage:
-Wl,-u,vfscanf -lscanf_min -lm