FSCANF(2)FSCANF(2)NAME
fscanf, scanf, sscanf, vfscanf - scan formatted input
SYNOPSIS
#include <u.h>
#include <stdio.h>
int fscanf(FILE *f, char *format, ...)
int scanf(char *format, ... )
int sscanf(char *s, char *format, ...)
int vfscanf(FILE *stream, char *format, char *args)
DESCRIPTION
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 subse‐
quent arguments as pointers to the objects to receive the converted
input. If there are insufficient arguments for the format, the behav‐
ior 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 charac‐
ter 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 speci‐
fication. 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 conversion 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. Sim‐
ilarly, 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 conversion 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 unavailability of input), or matching fail‐
ures (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 match‐
ing input sequences, as described below for each specifier. A conver‐
sion specification is executed in the following steps:
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 specifier. 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 following the format argument that has not already
received a conversion result. If this object does not have an appro‐
priate 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 correspond‐
ing 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 argument. The correspond‐
ing 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 argument. The corresponding argu‐
ment 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 corresponding argument shall be a pointer
to float.
s Matches a sequence of non-white-space characters. The corre‐
sponding 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 characters in the format string, up to and including
the matching right brace (]). The characters between the brack‐
ets (the scanlist) comprise the scanset, unless the character
after the left bracket is a circumflex (^), in which case the
scanset contains all characters that do not appear in the scan‐
list 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 character 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) function (in Plan 9, a hexadeci‐
mal number). The corresponding argument shall be a pointer to a
pointer to void. The interpretation of the input item is imple‐
mentation defined; however, for any input item other than a value
converted earlier during 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. Execu‐
tion 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 com‐
plete 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 direc‐
tive 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 input failure.
If conversion terminates on a conflicting input character, the offend‐
ing 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 suppressed 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.
SOURCE
/sys/src/libstdio
SEE ALSOfopen(2), fgetc(2)BUGS
Does not know about UTF.
FSCANF(2)
