scanf(3) CLIX scanf(3)
NAME
scanf, fscanf, sscanf - Converts formatted input
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stdio.h>
int scanf(
char *format ,
*additional arguments );
int fscanf(
FILE *stream ,
char *format ,
*additional arguments );
int sscanf(
char *string ,
char *format ,
*additional arguments );
PARAMETERS
format A string representing the way input data is to be interpreted
stream A stream from which data is taken
string A string from which data is taken
additional arguments
Pointers to input data
DESCRIPTION
The scanf() function reads from stdin The fscanf() function reads from the
named input stream. The sscanf() reads from the character string string.
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 additional arguments
indicating where the converted input should be stored. The results are
undefined if there are insufficient additional argumentss for the format.
If the format is exhausted while additional argumentss remain, the excess
additional arguments are simply ignored.
2/94 - Intergraph Corporation 1
scanf(3) CLIX scanf(3)
The control string usually contains conversion specifications, which are
used to direct interpretation of input sequences. The control string may
contain:
1. White space characters (blanks, tabs, newlines, or formfeeds) which,
except in two cases described below, cause input to be read up to the
next nonwhite-space character.
2. An ordinary 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), L, or h indicating the size of the
receiving variable, and a conversion code.
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 nonspace
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 A decimal integer is expected; the corresponding argument should
be an integer pointer.
u An unsigned decimal integer is expected; the corresponding
argument should be an unsigned integer pointer.
o An octal integer is expected; the corresponding argument should be
an integer pointer.
x A hexadecimal integer is expected; the corresponding argument
should be an integer pointer.
i an 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
2 Intergraph Corporation - 2/94
scanf(3) CLIX scanf(3)
(including white space) that have been scanned so far since the
function call. No input is consumed.
e,f,g 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 nonspace 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.
p An implementation-defined sequence of printable characters that
represent a pointer to a void. The corresponding argument should
be a pointer to a pointer to void. The implementation-defined
sequence of printable characters is the same as the sequence of
printable characters that is produced by the %p conversion of the
printf() function.
[ 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
2/94 - Intergraph Corporation 3
scanf(3) CLIX scanf(3)
match for this conversion to be considered successful.
The conversion characters d, i, n, u, o and x may be preceded by l (ell)
or h to indicate that a pointer to a short int or long int rather than a
pointer to an int is in the argument list. Similarly, the conversion
characters e, f, and g may be preceded by l (ell) to indicate a pointer to
double rather than to float, or by L to indicate a pointer to long double.
The l (ell), L, or h modifier is ignored for other conversion characters.
The scanf() function 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.
The scanf() function 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.
Trailing white space (including a newline) is left unread unless matched
in the control string.
EXAMPLES
1. To input a line containing an integer, a floating-point number and a
string:
int n;
float x;
char name[50];
n = scanf("%d%f%s", &i, &x, name);
Given the input line:
25 54.32E-1 joyce
The scanf() function will interpret will assign to n the value 3, to i
the value 25, to x the value 5.432, and name will contain joyce\0.
2. To skip input and partially ignore part of a string:
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
4 Intergraph Corporation - 2/94
scanf(3) CLIX scanf(3)
string 56\0 in name. The next call to getchar [see getc(3)] will
return a.
3. To use the %n format conversion code:
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(3)) will return a blank.
RETURN VALUES
These functions return EOF on end of input and a short count for missing
or illegal data items.
RELATED INFORMATION
Functions: getc(3), printf(3), stdio(3), strtod(3), strtol(3)
2/94 - Intergraph Corporation 5