SCANF(3S) BSD SCANF(3S)
NAME
scanf, fscanf, sscanf - formatted input conversion
SYNOPSIS
#include <stdio.h>
int scanf(format [, pointer ] . . . )
const char *format;
int fscanf(stream, format [, pointer ] . . . )
FILE *stream;
const char *format;
int sscanf(s, format [, pointer ] . . . )
const char *s, *format;
DESCRIPTION
scanf reads from the standard input stream stdin. fscanf reads from the
named input stream. sscanf reads from the character string s. Each
function reads characters, interprets them according to a format, and
stores the results in its arguments. Each expects as arguments a control
string format, described below, and a set of pointer arguments indicating
where the converted input should be stored.
The control string is a multibyte character sequence, beginning and
ending in its initial shift state. It usually contains conversion
specifications, which are used to direct interpretation of input
sequences. The control string is composed of zero or more directives:
o One or more white-space characters, which match optional white space
in the input.
o An ordinary multibyte character (not %) which must match the next
character of the input stream.
o Conversion specifications, consisting of the character "%," an
optional assignment suppressing character "*," an optional numerical
maximum field width, and a conversion character.
These functions execute each directive of the format in turn. If a
directive fails, they return. Failures are described as input failures
(due to the unavailability of input characters), or matching failures
(due to inappropriate input).
A conversion specification directs the conversion of the next input
field; the result is placed in the variable pointed to by the
corresponding argument, unless assignment suppression was indicated by
"*." An input field is defined as a string of non-space characters; it
extends to the next inappropriate character or until the field width, if
specified, is exhausted.
The conversion character indicates the interpretation of the input field;
the corresponding pointer argument must usually be of a restricted type.
The following conversion characters are legal:
% a single "%" is expected in the input at this point; no assignment is
done.
d An optionally signed decimal integer is expected; the corresponding
argument should be an integer pointer.
i An optionally signed integer is expected; the corresponding argument
should be an integer pointer.
o An optionally signed octal integer is expected; the corresponding
argument should be an unsigned integer pointer.
u An optionally signed decimal integer is expected; the corresponding
argument should be an unsigned integer pointer.
x An optionally signed hexadecimal integer is expected; the
corresponding argument should be an unsigned integer pointer.
s A character string is expected; the corresponding argument should be a
character pointer pointing to an array of characters large enough to
accept the string and a terminating `\0', which will be added. The
input field is terminated by a space character or a newline.
c A character is expected; the corresponding argument should be a
pointer to the initial character of an array large enough to accept
the sequence. No null character is added. The normal skip over space
characters is suppressed in this case; to read the next non-space
character, try "%1s." If a field width is given, the corresponding
argument should refer to a character array, and the indicated number
of characters is read.
e An optionally signed floating-point number is expected; the next field
f is converted accordingly and stored through the corresponding
g argument, which should be a pointer to a float. The input format for
floating point numbers is an optionally signed string of digits
possibly containing a decimal point, followed by an optional exponent
field consisting of an E or e followed by an optionally signed
integer.
[ Indicates a string not to be delimited by space characters. The left
bracket is followed by a set of characters and a right bracket; the
characters between the brackets define a set of characters making up
the string. If the first character is not circumflex (^), the input
field is all characters until the first character not in the set
between the brackets; if the first character after the left bracket is
"^," the input field is all characters until the first character which
is in the remaining set of characters between the brackets. If there
are two sequential delimiters in the input field, the remainder of the
pattern is not matched and the remaining fields will be returned as
zero or null. The corresponding argument must point to a character
array large enough to accept the sequence and a terminating null
character, which will be added automatically.
p A hexadecimal number resulting from the %p conversion of a pointer-
to-void by one of the printf family of functions is expected; the
corresponding argument should be a pointer to a pointer-to-void.
n No input is consumed. The corresponding argument should be a pointer
to an int into which is to be written the number of characters read
from the input stream so far by this call. A %n conversion does not
increment the assignment count returned by these functions.
The conversion specifiers E, G, and X are also valid and behave the same
as, respectively, e, g, and x. The conversion specifiers d, i, and n
must be preceded by h if the corresponding argument is a pointer to a
short int rather than a pointer to int, or by l (el) if it is a pointer
to long int. The conversion specifier D is synonymous with ld.
Similarly, the conversion specifiers o, u, and x must be preceded by h if
the corresponding argument is a pointer to unsigned short int rather than
a pointer to unsigned int, or by l if it is a pointer to unsigned long
int. The conversion specifiers O and X are synonymous with lo and lx,
respectively. Finally, the conversion specifiers e, f, and g must 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.
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 by way of the n conversion
specifier.
For example, the call
int n, i; 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". Or,
int i; float x; char name[50];
scanf("%2d%f%*d%[1234567890]", &i, &x, name);
with input
56789 0123 56a72
will assign 56 to i, 789.0 to x, skip "0123," and place the string "56\0"
in name. The next call to getchar will return "a".
SEE ALSO
atof(3), getc(3S), printf(3S)
DIAGNOSTICS
The scanf functions return the value of the macro EOF if an input failure
occurs before any conversion. Otherwise, they return the number of input
items assigned, which can be fewer than provided for, or even zero, in
the event of an early matching failure.
NOTE
Parts of this discussion are adapted from ANS X3.159-1989.
BUGS
The success of literal matches and suppressed assignments is not directly
determinable.