SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
NAME
scanf, fscanf, sscanf - convert formatted input
SYNOPSIS
#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *strm, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
DESCRIPTION
scanf reads from the standard input stream, stdin.
fscanf reads from the stream strm.
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. If there are insufficient
arguments for the format, the behavior is undefined. If the
format is exhausted while arguments remain, the excess argu-
ments are simply ignored.
The control string usually contains conversion specifica-
tions, which are used to direct interpretation of input
sequences. The control string may contain:
White-space characters (blanks, tabs, new-lines, or
form-feeds) that, except in two cases described below,
cause input to be read up to the next non-white-space
character.
An ordinary character (not %) that must match the next
character of the input stream.
Conversion specifications consisting of the character %
or the character sequence %digits$, an optional assign-
ment suppression character *, a decimal digit string
that specifies an optional numerical maximum field
width, an optional letter l (ell), L, or h indicating
the size of the receiving object, and a conversion
code. The conversion specifiers d, i, and n should 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 should 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.
Printed 11/19/92 Page 1
SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
Finally, the conversion specifiers e, f, and g should
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. The h, l, or L
modifier is ignored with any other conversion specif-
ier.
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 character *. The suppres-
sion of assignment provides a way of describing an input
field that is to be skipped. An input field is defined as a
string of non-space characters; it extends to the next inap-
propriate character or until the maximum field width, if
one is specified, is exhausted. For all descriptors except
the character [ and the character c, white space leading an
input field is ignored.
Conversions can be applied to the nth argument in the argu-
ment list, rather than to the next unused argument. In this
case, the conversion character % (see above) is replaced by
the sequence %digits$ where digits is a decimal integer n,
giving the position of the argument in the argument list.
The first such argument, %1$, immediately follows format.
The control string can contain either form of a conversion
specification, i.e., % or %digits$, although the two forms
cannot be mixed within a single control string.
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
valid:
% A single % is expected in the input at this point; no
assignment is done.
d Matches an optionally signed decimal integer, whose
format is the same as expected for the subject sequence
of the strtol function with the value 10 for the base
argument. The corresponding argument should be a
pointer to integer.
u Matches an optionally signed decimal integer, whose
format is the same as expected for the subject sequence
of the strtoul function with the value 10 for the base
argument. The corresponding argument should be a
pointer to unsigned integer.
o Matches an optionally signed octal integer, whose for-
mat is the same as expected for the subject sequence of
Page 2 Printed 11/19/92
SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
the strtoul function with the value 8 for the base
argument. The corresponding argument should be a
pointer to unsigned integer.
x Matches an optionally signed hexadecimal integer, whose
format is the same as expected for the subject sequence
of the strtoul function with the value 16 for the base
argument. The corresponding argument should be a
pointer to unsigned integer.
i Matches an optionally signed integer, whose format is
the same as expected for the subject sequence of the
strtol function with the value 0 for the base argument.
The corresponding argument should be a pointer to
integer.
n No input is consumed. The corresponding argument
should be a pointer to integer into which is to be
written the number of characters read from the input
stream so far by the call to the function. Execution
of a %n directive does not increment the assignment
count returned at the completion of execution of the
function.
e, f, g
Matches an optionally signed floating point number,
whose format is the same as expected for the subject
string of the strtod function. The corresponding argu-
ment should be a pointer to floating.
s A character string is expected; the corresponding argu-
ment 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 Matches a sequence of characters of the number speci-
fied by the field width (1 if no field width is present
in the directive). 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.
[ Matches a nonempty sequence of characters from a set of
expected characters (the scanset). The corresponding
argument should be a pointer to the initial character
of an array large enough to accept the sequence and a
terminating null character, which will be added
automatically. The conversion specifier includes all
subsequent characters in the format string, up to and
including the matching right bracket (]). The charac-
ters between the brackets (the scanlist) comprise the
Printed 11/19/92 Page 3
SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
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 scanlist
between the circumflex and the right bracket. 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; otherwise the first right
bracket character is the one that ends the specifica-
tion.
A range of characters in the scanset 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 character - will also stand
for itself whenever it is the first or the last charac-
ter in the scanlist. To include the right bracket as
an element of the scanset, it must appear as the first
character (possibly preceded by a circumflex) of the
scanlist and in this case it will not be syntactically
interpreted as the closing bracket. At least one char-
acter must match for this conversion to be considered
successful.
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 printf
function. The corresponding argument should be a
pointer to void. The interpretation of the input item
is implementation-defined. If the input item is a value
converted earlier during the same program execution,
the pointer that results shall compare equal to that
value; otherwise, the behavior of the %p conversion is
undefined.
If an invalid conversion character follows the %, the
results of the operation may not be predictable.
The conversion specifiers E, G, and X are also valid and,
under the -Xa and -Xc compilation modes [see cc(1)], behave
the same as e, g, and x, respectively. Under the -Xt compi-
lation mode, E, G, and X behave the same as le, lg, and lx,
respectively.
Each function allows for detection of a language-dependent
decimal point character in the input string. The decimal
point character is defined by the program's locale (category
LC_NUMERIC). In the C locale, or in a locale where the
decimal point character is not defined, the decimal point
character defaults to a period (.).
Page 4 Printed 11/19/92
SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
The scanf conversion terminates at end of file, at the end
of the control string, or when an input character conflicts
with the control string.
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; other-
wise, unless execution of the current directive is ter-
minated 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 new-line charac-
ters) 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.
EXAMPLES
The call to the function scanf:
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.
SEE ALSO
cc(1), printf(3S), strtod(3C), strtol(3C), strtoul(3C).
DIAGNOSTICS
These routines return the number of successfully matched and
assigned input items; this number can be zero in the event
Printed 11/19/92 Page 5
SCANF(3S-SVR4) RISC/os Reference Manual SCANF(3S-SVR4)
of an early matching failure between an input character and
the control string. If the input ends before the first
matching failure or conversion, EOF is returned.
Page 6 Printed 11/19/92