SCANF(3S) SysV SCANF(3S)
NAME
scanf, fscanf, sscanf - convert formatted input
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 results are
undefined in there are insufficient args for the format. If the format
is exhausted while args remain, the excess args are simply ignored.
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:
1. White-space characters which, except in two cases described below,
cause input to be read up to the next non-white-space character.
2. An ordinary multibyte character (not %), which must match the next
character of the input stream.
3. Conversion specifications, consisting of the character %, an optional
assignment suppressing character *, an optional numerical maximum
field width, an optional l (ell) or h indicating the size of the
receiving variable, and a conversion code.
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 *.
The suppression of assignment provides a way of describing an input field
which is to be skipped. 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. For all descriptors except
"[" and "c", white space leading an input field is ignored.
The conversion code indicates the interpretation of the input field; the
corresponding pointer argument must usually be of a restricted type. For
a suppressed field, no pointer argument is given. The following
conversion codes 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.
u an optionally signed decimal integer is expected; the
corresponding argument should be an unsigned integer pointer.
o an optionally signed octal 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.
i an optionally signed integer is expected; the corresponding
argument should be an integer pointer. It will store the value of
the next input item interpreted according to C conventions: a
leading "0" implies octal; a leading "0x" implies hexadecimal;
otherwise, decimal.
n stores in an integer argument the total number of characters
(including white space) that have been scanned so far since the
function call. No input is consumed.
e,f,g an optionally signed floating point number is expected; the next
field is converted accordingly and stored through the
corresponding 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 an
e, followed by an optional +, -, or space, followed by an
integer.
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 automatically. The input field is terminated by a white-
space character.
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 white space is suppressed in this case; to read the
next non-space character, use %1s. If a field width is given,
the corresponding argument should refer to a character array; the
indicated number of characters is read.
[ indicates string data and the normal skip over leading white
space is suppressed. The left bracket is followed by a set of
characters, which we will call the scanset, and a right bracket;
the input field is the maximal sequence of input characters
consisting entirely of characters in the scanset. The circumflex
(^), when it appears as the first character in the scanset,
serves as a complement operator and redefines the scanset as the
set of all characters not contained in the remainder of the
scanset string. There are some conventions used in the
construction of the scanset. A range of characters may be
represented by the construct first-last, thus [0123456789] may be
expressed [0-9]. Using this convention, first must be lexically
less than or equal to last, or else the dash will stand for
itself. The dash will also stand for itself whenever it is the
first or the last character in the scanset. To include the right
square bracket as an element of the scanset, it must appear as
the first character (possibly preceded by a circumflex) of the
scanset, and in this case it will not be syntactically
interpreted as the closing bracket. The corresponding argument
must point to a character array large enough to hold the data
field and the terminating \0, which will be added automatically.
At least one character must match for this conversion to be
considered successful.
p matches an eight-digit hexadecimal number resulting from the %p
conversion of a pointer-to-void by one of the printf family of
functions; the corresponding argument should be a pointer to a
pointer-to-void.
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 short
int rather than a pointer to int, or by l if it is a pointer to long int.
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. 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
point 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.
scanf conversion terminates at EOF, at the end of the control string, or
when an input character conflicts with the control string. In the latter
case, the offending character is left unread in the input stream.
scanf returns the number of successfully matched and assigned input
items; this number can be zero in the event of an early conflict between
an input character and the control string. If the input ends before the
first conflict or conversion, EOF is returned.
EXAMPLES
The call:
int 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 . Or:
int i, j; float x; char name[50];
(void) scanf("%i%2d%f%*d %[0-9] ", &j, &i, &x, name);
with input:
011 56789 0123 56a72
will assign 9 to j, 56 to i, 789.0 to x, skip 0123, and place the string
56\0 in name. The next call to getchar [see getc(3S)] will return a.
Or:
int i, j, s, e; char name[50];
(void) scanf("%i %i %n%s%n", &i, &j, &s, name, &e);
with input:
0x11 0xy johnson
will assign 17 to i, 0 to j, 6 to s, will place the string xy\0 in name,
and will assign 8 to e. Thus, the length of name is e - s = 2 . The
next call to getchar (see getc(3S)) will return a blank.
SEE ALSO
getc(3S), printf(3S), stdio(3S), strtod(3C), strtol(3C).
DIAGNOSTICS
These 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.
CAVEATS
Trailing white space (including a newline) is left unread unless matched
in the control string.