scanf(3s) DG/UX 4.30 scanf(3s)
NAME
scanf, fscanf, sscanf - convert formatted input
SYNOPSIS
#include <stdio.h>
int scanf (format [ , arg ] ... )
char *format;
int fscanf (stream, format [ , arg ] ... )
FILE *stream;
char *format;
int sscanf (s, format [ , arg ] ... )
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 using subsequent arguments, arg, as pointers to the
objects to receive the converted input. The results are
undefined if there are insufficient args for the format. If
the format is exhausted while args remain, the excess args
are simply ignored.
The format string usually contains conversion
specifications, which are used to direct interpretation of
input sequences. The format string is composed of zero or
more directives:
1. One or more white-space characters (blanks, tabs, new-
lines, or form-feeds) which, except in two cases
described below, cause input to be read up to the next
non-white-space character.
2. An ordinary character (neither % nor a white-space
character ), which must match the next character of the
input stream.
3. Conversion specifications, each of which results in
fetching zero or more subsequent args.
A conversion specification is introduced by the character %.
After the %, the following appear in sequence:
- An optional assignment suppressing character (*)
- An optional decimal integer that specifies the maximum
field width.
- An optional h, l (ell) or L indicating the size of the
receiving object. The conversion specifiers d, i, and n
Licensed material--property of copyright holder(s) Page 1
scanf(3s) DG/UX 4.30 scanf(3s)
shall be preceeded by h if the corresponding arg is a
pointer to a short int rather than a pointer to an int, or
by l if it is a pointer to a long int. Similarly, the
conversion specifiers o, u, and x shall be preceeded by h
if the corresponding arg is a pointer to an unsigned short
int rather than a pointer to an unsigned int, or by l if
it is a pointer to unsigned long int. Finally, the
conversion specifiers e, f, and g shall be preceeded by l
if the corresponding arg is a pointer to double rather
than a pointer to float, or by L if it is a pointer to
long double.
- A character that specifies the type of conversion to be
applied. The valid conversion specifiers are described
below.
Each scanf family function executes each directive in the
format in turn. If a directive fails, as detailed below,
the function returns. Failures are described as input
failures (due to the unavailability of input characters), or
matching failures (due to inappropriate input).
A directive composed of white-space characters 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 (neither % or
white-space characters) is executed by reading the next
characters of the stream. If one of the characters differs
from 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:
1. Input white-space characters (as specified by the isspace
function) are skipped, unless the specification contains
a n,c, or n specifier.
2. An input item is read from the stream, unless the
specification includes an n specifier. An input item is
defined as the longest matching sequence of input
characters, unless that exceeds a specified field width,
in which case it is the initial subsequence of that
length in the sequence. The first character, if any,
after the input item remains unread. If the length of
the input item is zero, the execution ot the directive
fails: this condition is a matching failure, unless an
error prevented input from the stream, in which case it
Licensed material--property of copyright holder(s) Page 2
scanf(3s) DG/UX 4.30 scanf(3s)
is an input failure.
3. 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 itme 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 arg following the format argument that has not
already received a conversion result.
The following conversion specifiers are valid:
% 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.
p matches the same input sequences as the %p conversion
specifier of printf produces. The corresponding arg
shall be a pointer to a pointer to void.
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; execution of a %n directive does not
increment the assignment count returned at the
completion of function execution.
e,f,g
Licensed material--property of copyright holder(s) Page 3
scanf(3s) DG/UX 4.30 scanf(3s)
a 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 character pointer. 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.
scanf conversion terminates at EOF, at the end of the
Licensed material--property of copyright holder(s) Page 4
scanf(3s) DG/UX 4.30 scanf(3s)
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 EOF on end of input and a short count
for missing or illegal data items.
Licensed material--property of copyright holder(s) Page 5
scanf(3s) DG/UX 4.30 scanf(3s)
CAVEATS
Trailing white space (including a new-line) is left unread
unless matched in the control string.
Licensed material--property of copyright holder(s) Page 6