6.18.50 vfscanf Function
Scans formatted data from a stream using a variable length argument list.
Include
<stdio.h>
Prototype
int vfscanf(FILE * restrict stream, const char * restrict format,
va_list arg);
Arguments
stream- pointer to the open stream
format- format control string
arg- pointer to a list of arguments
Return Value
If an input failure occurs before any conversion. the function returns the value of the
macro EOF; otherwise, it returns the number of input items assigned.
Remarks
To access the variable length argument list, the arg variable must be
initialized by the macro va_start and may be reinitialized by additional
calls to va_arg. This must be done before the vfscanf
function is called. Invoke va_end after the function returns.
When building with MPLAB XC16 or XC-DSC, this function requires a heap.
To reduce code size, the functionality of this routine can be automatically customized by the compiler with each build. See the Smart IO Routines section in your compiler's user's guide for more information on the options that control this feature.
The format string can be composed of white space characters, which
reads input up to the first non-white-space character in the input; or ordinary
multibyte characters, which if not read in that order, will trigger an error and
leave the remaining characters in the input, unread. The format string can also
contain conversion specifications, which begin with the % character
and that specify the expected input sequences and how they are to be converted for
assignment to objects pointed to by the pointer arguments.
Each conversion specification begins with a percent character followed by optional fields and a required type as shown here:
%[*][width][length]specifier
The presence of * immediately after the percent character indicates
that the read and converted value should not be assigned to any object.
The width is a decimal integer that must be
non-zero and indicates the maximum field width (in characters) of the input that is
read to match the specification.
The length modifier specifies the size of the
object in which the value will be assigned, as described in the following table.
Their use with other conversion specifiers results in undefined behavior.
| Modifier | Meaning |
|---|---|
h |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a short
int or unsigned short int object
referenced by the pointer argument. |
hh |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a signed
char or unsigned char object
referenced by the pointer argument. |
l |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a long
int or unsigned long int object
referenced by the pointer argument. |
l |
When used the a,
A, e, E,
f, F, g, or
G indicates that this conversion specifier
assigns to a double object referenced by the
pointer argument. |
l |
When used the c,
s, or [ indicates that this
conversion specifier assigns to a wchar_t object
referenced by the pointer argument. |
ll |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a long
long int or unsigned long long int
object referenced by the pointer argument. |
L |
When used the a,
A, e, E,
f, F, g,
G conversion specifier, indicates the argument
value is a long double. |
j |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a
intmax_t or uintmax_t object
referenced by the pointer argument. |
t |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a
ptrdiff_t object referenced by the pointer
argument. |
z |
When used with d,
i, o, u,
x, X, or n
indicates that this conversion specifier assigns to a
size_t object referenced by the pointer
argument. |
The conversion specifiers specify the type of
conversion to be applied to the read sequence.
| Specifier | Receiving object type | Matches |
|---|---|---|
a |
double |
Matches an optionally signed floating-point
number, infinity, or NaN, whose format is the same as expected by
the strtod function for the first argument. |
c |
char array, or wchar_t
array |
Matches a single character or the number of
characters specified by the field width if present. If an
l length modifier is present, the input shall
be a sequence of multibyte characters, converted to a wide character
as if by a call to the mbrtowc function. No null
character or wide character is added. |
d |
signed int |
Matches an optionally signed decimal
integer, whose format is the same as expected by the
strtod function for the first argument when
using a value of 10 for the base argument. |
e |
double |
Matches an optionally signed floating-point
number, infinity, or NaN, whose format is the same as expected by
the strtod function for the first argument. |
f |
double |
Matches an optionally signed floating-point
number, infinity, or NaN, whose format is the same as expected by
the strtod function for the first argument. |
g |
double |
Matches an optionally signed floating-point
number, infinity, or NaN, whose format is the same as expected by
the strtod function for the first argument. |
i |
signed int |
Matches an optionally signed decimal
integer, whose format is the same as expected by the
strtod function for the first argument when
using a value of 0 for the base argument. |
n |
int |
No input is consumed but the number of characters this call has so far read from the input stream is written to the argument with no increment of the assignment count returned by the function. If the conversion specification includes an assignment-suppressing character or a field width, the behavior is undefined. |
o |
unsigned int |
Matches an optionally signed decimal
integer, whose format is the same as expected by the
strtoul function for the first argument when
using a value of 8 for the base argument. |
p |
void * * |
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 function. The input item is converted to a pointer value in an implementation-defined manner. If the input item is a value converted earlier during the same program execution, the pointer that results shall compare equal to that value; otherwise the behavior of the %p conversion is undefined. |
s |
char array, or wchar_t
array |
Matches a sequences of non-white-space characters, which is
written to the array argument and appended with a null
terminating character. If an |
x |
unsigned int |
Matches an optionally signed decimal
integer, whose format is the same as expected by the
strtoul function for the first argument when
using a value of 16 for the base argument. |
% |
Matches a single %
character. No assignment takes place. |
|
[ |
char array, or wchar_t
array |
Matches all the characters in the input
that have been specified between the [ and trailing
] character, unless the character after the
opening bracket is a circumflex, ^, in which case a
match is only made with characters that do not appear in the
brackets. If the conversion specifier begins with
[] or [^], the right bracket
character will match the input and the next following right bracket
character is the matching right bracket that ends the specification.
A null character will be appended to the characters read. If an
l length modifier is present, the input shall
be a sequence of multibyte characters and a null wide character will
be appended to the matched wide characters. |
Example
#include <stdio.h>
#include <stdarg.h>
void readArgs(FILE * stream, const char * format, ...)
{
va_list args;
va_start(args, format);
vfscanf(stream, format, args);
va_end(args);
}
int main(void)
{
FILE * myfile;
int val;
char str[20];
myfile = fopen("afile", "r");
if(myfile!=NULL) {
readArgs( myfile, "%s %d", str, &val);
printf("String and value read: %s and %d\n", str, val);
fclose(myfile);
}
}Example Input
Contents of afile.txt
Start 23
Stop 0Example Output
String and value read: Start and 23