|
|
#include <stdio.h>int fscanf(FILE
strm, const char
int scanf(const char
int sscanf(const char
#include <stdarg.h>
int vfscanf(FILE
int vscanf(const char
int vsscanf(const char
scanf- convert formatted input read from the standard input stream
sscanf- convert formatted input read from a character string
vfscanf- convert formatted input read from a named stream
vscanf- convert formatted input read from the standard input stream
vsscanf- convert formatted input read from a character string
Each function reads characters, interprets them,
and stores the results through the arg pointers,
under control of the character string format.
Each function returns the number of
successfully matched and assigned input items,
or EOF if the input ended prior any successful matches.
fscanf and vfscanf read from the stream strm.
scanf and vscanf read from the standard input stream, stdin.
sscanf and vsscanf read from the character string s.
The ``v'' functions take their pointer arguments through the single va_list object passed. See stdarg(5).
The format consists of zero or more portable white-space characters (blanks, horizontal and vertical tabs, newlines, carriage returns, and form-feeds) which cause single-byte white-space input characters [as defined by isspace, see ctype(3C)] to be skipped, zero or more ordinary characters (not %) which must match the next input characters, and zero or more conversion specifications, each of which is introduced by the a % which can result in the matching of a sequence of input characters and possibly the assignment of a converted value.
Each conversion specification takes the following general form and sequence:
%[pos$][
When numbered argument specifications are used, specifying the Nth argument requires that all the preceding arguments, from the first to the (N-1)th, be specified at least once, in a consistent way, in the format string.
If a size appears other than in these combinations, the behavior is undefined.
A conversion specification directs the
matching and conversion of the next input item;
the result is placed in the object pointed to
by the corresponding arg unless assignment suppression
was indicated by the flag.
The suppression of assignment provides a way of
describing an input item that is to be skipped.
For all conversion specifiers except
c, C, n and [...],
leading single-byte white-space characters are skipped.
An input item is usually defined
as a sequence of non-white-space single-byte characters
that extends to the next inappropriate single-byte character
or until the maximum field width
(if one is specified)
is exhausted.
For C, S and l[...],
the field width instead specifies the number of multibyte characters.
The conversion specifiers and their meanings are:
For [...] and l[...], the scanlist consists of all characters up to, but not including, the matching right bracket (]). The first right bracket matches unless the specifier begins with [] or [^], in which case the scanlist includes a ] and the matching one is the second right bracket. The scanset is those characters described by the scanlist unless it begins with a circumflex (^), in which case the scanset is those characters not described by the scanlist that follows the circumflex. The scanlist can describe an inclusive range of characters by low-high where low is not lexically greater than high (and where these endpoints are in the same codeset for l[...] in locales whose multibyte characters have such); otherwise, a dash (-) will stand for itself, as it will when it occurs last in the scanlist, or the first, or the second when a circumflex is first.
If the form of the conversion specification does not match any of the above, the results of the conversion are undefined. Similarly, the results are undefined if there are insufficient pointer args for the format. If the format is exhausted while args remain, the excess args are ignored.
When matching floating numbers, the locale's decimal point character is taken to introduce a fractional portion, the sequences inf and infinity (case ignored) are taken to represent infinities, and the sequence nan[(m)] (case ignored), where the optional parenthesized m consists of zero or more alphanumeric or underscore (_) characters, are taken to represent NaNs (not-a-numbers). Note, however, that the locale's thousands' separator character will not be recognized as such.
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.
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 (other than %n, if any) is terminated with an input failure.
If a truncated sequence (due to reaching end-of-file or a conflicting input character, or because a field width is exhausted) does not form a valid match for the current directive, the directive is terminated with a matching failure.
The success of literal matches and suppressed assignments is not directly determinable other than via the %n directive.
Characters from streams (stdin or strm) are read as if the getc function had been called repeatedly.
EOF is returned.
The functions fscanf and scanf fail when data needs to be read, the file is a regular file, and an attempt was made to read at or beyond the offset maximum associated with the corresponding stream.
int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name);
with the input line:
25 54.32E-1 thompson
will assign to n the value 3, to i the value 25, to x the value 5.432, and name will contain thompson\0.
The call to the function scanf:
int i; float x; char name[50];
(void) scanf("%2d%f%d %[0-9]", &i, &x, name);
with the input line:
56789 0123 56a72
will assign 56 to i, 789.0 to x, skip 0123, and place the characters 56\0 in name. The next character read from stdin will be a.
The following shows a simple use of vfscanf, a function that reads formatted input from its own connection to /dev/tty.
#include <stdarg.h> #include <stdio.h>static FILE *instream;
int scan(const char *fmt, ...) { va_list ap; int ret;
va_start(ap, fmt); if (instream == 0) { if ((instream = fopen("/dev/tty", "r")) == 0) return EOF; } ret = vfscanf(instream, fmt, ap); va_end(ap); return ret; }