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 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:
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 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 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:
[ 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
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 hexadecimal number). The corresponding argument shall be a pointer to a pointer to void. The interpretation of the input
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 input failure. 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 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 ALSO
fopen(2), fgetc(2) |
BUGS
Does not know about UTF. |