scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf
Purpose
Converts formatted input.
Library
Standard I/O Library (libc.a)
Syntax
#include <stdio.h>
int scanf (fmt [, ptr, ... |) int NLscanf (fmt [, ptr, ... |)
char *fmt; char *fmt;
int fscanf (stream, fmt [, ptr, ... |int NLfscanf (stream, fmt [, ptr, ... |)
FILE *stream; FILE *stream;
char *fmt; char *fmt;
int sscanf (s, fmt [, ptr, ... |) int NLsscanf (s, fmt [, ptr, ... |)
char *s, *fmt; char *s, *fmt;
Description
The scanf, fscanf, and sscanf subroutines read character
data, interpret it according to a format, and store the
converted results into specified memory locations. The
NLscanf, NLfscanf, and NLsscanf subroutines parallel
their corresponding functions, providing conversion types
to handle NLchars as well as chars. These subroutines
read their input from the following sources:
scanf, NLscanf Reads from standard input (stdin).
fscanf, NLfscanf Reads from stream.
sscanf, NLsscanf Reads from the character string s.
The fmt parameter contains conversion specifications used
to interpret the input. The ptr parameters specify where
to store the interpreted data.
The fmt parameter can contain the following:
o White space characters (blanks, tabs, new-lines, or
form-feeds) which, except in two cases described fol-
lowing, reads the input up to the next nonwhite space
character. Unless there is a match in the control
string, trailing white space (including a new-line
character) is not read.
o Any character except "%" (percent), which must match
the next character of the input stream.
o A conversion specification that directs the conver-
sion of the next input field. It consists of the
following:
1. The character "%" (percent)
2. An optional assignment suppression character, *
(asterisk)
3. An optional numeric maximum field width
4. An optional character that sets the size of the
receiving variable as for some flags, as follows:
l Signed long integer rather than an int when
preceding the d, u, o or x conversion codes.
A double rather than a float, when preceding
the e, f or g conversion codes.
h Signed short integer (half int) rather than an
int when preceding the d, u, o or x conversion
codes.
5. A conversion code.
The conversion specification is of the form:
%[*][width][size]convcode
The results from the conversion are placed in *ptr unless
you specify assignment suppression with *. Assignment
suppression provides a way to describe an input field
that is to be skipped. The input field is a string of
nonwhite-space characters. It extends to the next inap-
propriate character or until the field width, if speci-
fied, is exhausted.
The conversion code indicates how to interpret the input
field. The corresponding ptr must usually be of a
restricted type. You should not specify ptr for a sup-
pressed field. You can use the following conversion
codes:
"%" Accepts a single "%" input at this point; no
assignment is done.
d Accepts a decimal integer; ptr should be an
integer pointer.
u Accepts an unsigned decimal integer; ptr should
be an unsigned integer pointer.
o Accepts an octal integer; ptr should be an
integer pointer.
x Accepts a hexadecimal integer; ptr should be an
integer pointer.
e, f, g Accepts a floating-point number. The next field
is converted accordingly and stored through the
corresponding parameter, which should be a
pointer to a float. The input format for
floating-point numbers is a string of digits,
with some optional characteristics:
o It can be a signed value.
o It can be an exponential value, containing a
decimal point followed by an exponent field,
which consists of an E or an e followed by
an (optionally signed) integer.
o It can be one of the special values INF,
QNAN, or SNAN, which is translated into the
ANSI/IEEE value for infinity, quiet NaN, or
signalling NaN, respectively.
s Accepts a string of chars. The ptr parameter
should be a character pointer that points to an
array of characters large enough to accept the
string and ending with "'\0'". The "'\0'" is
added automatically. The input field ends with
a white space character. A string of chars is
output.
S (Used by the NLscanf, NLfscanf, and NLsscanf
subroutines only.) Accepts an NLchar string.
The ptr parameter should point to an array of
characters large enough to accept the string and
end with "'\0'". The "'\0'" is added automat-
ically. The input field ends with a white space
character. A string of NLchars is output.
N (Used by the NLscanf, NLfscanf, and NLsscanf
subroutines only.) Accepts an ASCII string,
possibly containing extended character informa-
tion in the form of escape sequences used by the
NLescstr and NLunescstr subroutines. (See
"display symbols" for a list of these escape
sequences.) The output is in the form of
NLchars.
c A character is expected. The ptr parameter
should be a character pointer. The normal skip
over white space is suppressed. Use "%"1s to
read the next nonwhite-space character. If a
field width is given, ptr should refer to a
character array; the indicated number of charac-
ters is read.
[scanset| Accepts as input the characters included in the
scanset. The scanset explicitly defines the
characters that are accepted in the string data
as those enclosed within square brackets. The
normal skip over leading white space is sup-
pressed. A scanset in the form of [^scanset] is
an exclusive scanset: the ^ (circumflex) serves
as a complement operator and the following char-
acters in the scanset are not accepted as input.
Conventions used in the construction of the
scanset follow:
o You can represent a range of characters by
the construct first-last. Thus you can
express [0123456789] as [0-9]. The first
parameter must be lexically less than or
equal to last, or else the - (dash) stands
for itself. The - also stands for itself
whenever it is the first or the last char-
acter in the scanset.
o You can include the ] (right bracket), as an
element of the scanset, if it is the first
character of the scanset. In this case it
is not interpreted as the bracket that
closes the scanset. If the scanset is an
exclusive scanset, the ] is preceded by the
^ (circumflex) to make the ] an element of
the scanset. The corresponding ptr must
point to a character array large enough to
hold the data field and that ends with
"'\0'". The "'\0'" is added automatically.
A scanf or NLscanf conversion ends at the end-of-file,
the end of the control string, or when an input character
conflicts with the control string. If it ends with an
input character conflict, the character that conflicts is
not read from the input stream.
Unless there is a match in the control string, trailing
white space (including a new-line character) is not read.
The success of literal matches and suppressed assignments
is not directly determinable.
Return Value
Each of these subroutines returns the display length of
the string it outputs, which is the number of the display
characters in the string, rather than the number of
bytes. These subroutines return an EOF on the end of
input and on a short count for missing or illegal data
items.
The scanf and NLscanf subroutines return the number of
successfully matched and assigned input items. This
number can be 0 if there was an early conflict between an
input character and the control string. If the input
ends before the first conflict or conversion, only EOF is
returned.
Examples
1. To read several values and assign them to variables:
int i;
float x;
char name[50];
scanf ("%d%f%s", &i, &x, name);
with the input line:
25 54.32E-1 thompson
This assigns to "i" the value "25", to "x" the value
"5.432", and to "name" the value "thompson\0".
2. To perform simple pattern-matching while scanning the
input:
int i;
float x;
char name[50];
scanf ("%2d%f%*d%[0-9]", &i, &x, name);
with the input:
56789 0123 56a72
This assigns "56" to "i", "789.0" to "x", skips
"0123", and places the string "56\0" in "name". The
next call to getchar (see "getc, fgetc, getchar,
getw") returns "a".
Related Information
In this book: "printf, fprintf, sprintf, NLprintf,
NLfprintf, NLsprintf," "getc, fgetc, getchar, getw,"
"standard i/o library," "strtod, atof," "strtol, atol,
atoi," and "display symbols."
Examples of using scanf in C Language Guide and
Reference.
"Overview of International Character Support" in Managing
the AIX Operating System.