 |
» |
|
|
|
NAMEscanf, fscanf, sscanf — formatted input conversion, read from stream file SYNOPSIS#include <stdio.h> int scanf(const char *__restrict format, /* [pointer,] */ ...); int fscanf(FILE *__restrict stream, const char *__restrict format, /* [pointer,] */ ...); int sscanf(const char *__restrict s, const char *__restrict format, /* [pointer,] */ ...); DESCRIPTIONscanf()
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 the control string
format
argument, and stores the results in its
pointer
arguments.
If there are insufficient arguments for the format,
the behavior is undefined.
If the format is exhausted while arguments remain,
the excess arguments are ignored.
The control string contains conversion specifications and other characters
used to direct interpretation of input sequences.
The control string contains:
White-space characters (blanks, tabs, newlines, or formfeeds)
that cause input to be read up to the next
non-white-space character (except in two cases described
below). An ordinary character (not
%)
that must match the next character of the input stream. Conversion specifications, consisting of the character
%,
an optional assignment suppressing character
*,
an optional numerical maximum-field width, an optional
h,
hh,
j,
l (ell),
L,
ll (ell ell),
t,
or
z
indicating the size of the receiving variable and a conversion code. The conversion specification can alternatively be prefixed
by the character sequence
%n$
instead of the character
%,
where
n
is a decimal integer in the range
(1-{NL_ARGMAX})
(NL_ARGMAX
is defined in
<limits.h>).
The
%n$
construction indicates that the value of the next input field
should be placed in the
nth
argument, rather than to the next unused one.
The two forms of introducing a conversion specification,
%
and
%n$,
must not be mixed within a single
format
string with the following exception:
Skip fields (see below) can be designated as
%*
or
%n$*.
In the latter case,
n
is ignored.
Unless the specification contains the
n
conversion character (described below),
a conversion specification directs the conversion of the next input field.
The result of a conversion specification is placed in the variable
to which the corresponding argument points, unless
*
indicates assignment suppression.
Assignment suppression provides a way to describe an
input field 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
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 unsigned integer pointer. - x, X
A hexadecimal integer is expected;
the corresponding argument should be an unsigned integer pointer.
The
x
and
X
conversion characters are equivalent. - i
An integer is expected;
the corresponding argument should be an integer pointer.
The value of the next input item, interpreted according
to C conventions, will be stored; a leading
0
implies octal, a leading
0x
implies hexadecimal; otherwise, decimal is assumed. - hL
An
extended
type is expected; the corresponding argument should be an
extended
pointer which is the 80-bit IEEE-754 double-extended type in
the
Itanium®
architecture; should be used with the floating-point
specifiers
a,
A,
e,
E,
f,
F,
g,
and
G. - n
Cause the total number of bytes (including white space)
scanned since the function call to be stored;
the corresponding argument should be an integer pointer.
No input is consumed.
The function return value does not include
%n
assignments in the count of successfully matched and assigned input items. - a,A,e,E,f,F,g,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 radix character, followed by
an optional exponent field consisting of an
E
or an
e,
followed by an optional
+,
-,
or space, followed by an integer.
For Itanium(R)-based systems only, hexadecimal floating-point input also is accepted:
the format is an optionally signed
string of hexadecimal digits, possibly containing a radix character,
followed by
an optional binary exponent field (indicating the power of two by
which the significant part is to be scaled) consisting of a
P
or a
p,
followed by an optional
+,
-,
or space, followed by a decimal integer.
The conversion characters
A,
E,
F,
and
G
behave the same as, respectively,
a,
e,
f,
and
g.
The
a,
A,
e,
E,
f,
F,
g,
and
G
conversions will convert the string
inf
(case insensitive) or the string
infinity
(case insensitive) to the appropriate floating point infinity
value (single, double, or quadruple precision, as specified by the
conversion precision modifier).
The
a,
A,
e,
E,
f,
F,
g,
and
G
conversions will convert the string
nan
(case insensitive) to the appropriate floating point
NaN
value (single, double, or quadruple precision, as specified by
the conversion precision modifier). - 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
refers to a character array; the indicated number of characters is read. If an
l
(ell) qualifier is present, the input is a sequence of characters that
begins in the initial shift state.
Each character in the sequence is converted to a wide-character as if by
a call to the
mbrtowc()
function, with the conversion state described by an
mbstate_t
object initialized to zero before the first character is converted.
The corresponding argument must be a pointer to an array of
wchar_t
large enough to accept the resulting sequence of wide-characters.
No null wide-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 refers to a wide character array;
the indicated number of characters is read and converted. - C
Same as
lc. - 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 is added automatically.
The input field is terminated by a white-space character.
scanf()
cannot read a null string. If an
l
(ell) qualifier is present, the input is a sequence of characters that
begins in the initial shift state.
Each character is converted to a wide-character as if by a call to the
mbrtowc()
function, with the conversion state described by an
mbstate_t
object initialized to zero before the first character is converted.
The corresponding argument must be a pointer to an array of
wchar_t
large enough to accept the sequence and the terminating null wide-character,
which will be added automatically.
The input field is terminated by a white-space character.
scanf()
cannot read a null string. - S
Same as
ls. - [
Indicates string data and the normal skip-over-leading-white-space
is suppressed.
The left bracket is followed by a set of characters, called 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.
Construction of the
scanset
follows certain conventions.
A range of characters may be represented by the construct
first-last,
enabling [0123456789] to be expressed [0-9].
Using this convention,
first
must be lexically less than or equal to
last;
otherwise, the dash stands for itself. The dash also stands for
itself when 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, in which case it will not
be interpreted syntactically 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 are added automatically.
At least one character must match for this conversion to succeed. If an
l
(ell) qualifier is present, the input is a sequence of characters that
begins in the initial shift state.
Each character in the sequence is converted to a wide-character as if by
a call to the
mbrtowc()
function, with the conversion state described by an
mbstate_t
object initialized to zero before the first character is converted.
The corresponding argument must be a pointer to an array of
wchar_t
large enough to accept the sequence and the terminating null wide-character,
which will be added automatically. - p
A sequence of unsigned hexadecimal numbers is expected.
This sequence may be produced by the
p
conversion character of
printf().
The corresponding argument shall be a pointer to a pointer to
void
into which the value represented by the hexadecimal sequence is stored.
The behavior of this conversion is undefined for any input item
other than a value converted earlier during the same program execution.
The conversion characters
d,
i,
and
n
can be preceded by
h,
hh,
j,
l,
ll,
t,
or
z
to indicate that a pointer to a
short int,
signed char,
intmax_t,
long int,
long long int,
ptrdiff_t,
or
ssize_t
rather than to an
int
is in the argument list.
Similarly, the conversion characters
u,
o,
x,
and
X
can be preceded by
h,
hh,
j,
l,
ll,
t,
or
z
to indicate that a pointer to a
unsigned short int,
unsigned char,
uintmax_t,
unsigned long int,
unsigned long long int,
unsigned ptrdiff_t,
or
size_t
rather than to an
unsigned int
is in the argument list.
Finally, the conversion characters
e,
E,
f,
F,
g,
and
G
can be preceded by
l
or
L
to indicate that a pointer to a
double
or
long
double
rather than to a
float
is in the argument list.
The
h,
hh,
j,
l,
L,
ll,
t,
or
z
modifier is ignored for other conversion characters. The
scanf()
functions terminate their conversions 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. EXTERNAL INFLUENCESLocaleThe
LC_CTYPE
category determines the interpretation of ordinary characters
within format strings as single and/or multi-byte characters.
Field width is given in terms of bytes.
Characters received from the input stream are interpreted
as single- or multi-byte characters as determined by the
LC_TYPE
category and the field width is decremented by the length of the character. The
LC_NUMERIC
category determines the radix character
expected within floating-point numbers. International Code Set SupportSingle- and multi-byte character code sets are supported. RETURN VALUEIf the input ends before the first conflict or conversion,
EOF
is returned.
Otherwise, these functions return the number
of successfully assigned input items.
This number is a short count, or even zero if a conflict
ensues between an input character and the control string. ERRORSscanf()
and
fscanf()
fail if data needs to be read into the
stream's
buffer, and:
- EAGAIN
The
O_NONBLOCK
flag is set for the file descriptor underlying
stream
and the process would be delayed in the read operation. - EBADF
The file descriptor underlying
stream
is not a valid file descriptor open for reading. - EINTR
The read operation was terminated due to the receipt of a signal,
and either no data was transferred
or the implementation does not report partial transfer for this file. - EIO
The process is a member of a background process
and is attempting to read from its controlling terminal,
and either the process is ignoring or blocking the
SIGTTIN
signal or the process group of the process is orphaned. - [EILSEQ]
The data obtained from the input stream does not form a valid wide character.
Additional
errno
values can be set by the underlying
read()
function (see
read(2)). EXAMPLESThe call:
int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name); with the input line:
assigns to
n
the value
3,
to
i
the value
25,
to
x
the value
5.432,
and
name
contains
thompson\0.
Or:
int i; float x; char name[50];
(void) scanf("%2d%f%*d %[0-9]", &i, &x, name); with input:
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(3S))
returns
a. For another example,
to create a language-independent date scanning routine, use:
char month[20]; int day, year;
(void) scanf(format, month, &day, &year); For American usage,
format
would point to a string:
The input:
would assign
July
to
month,
3
to
day
and
1986
to
year. For German usage,
format
would point to a string:
The input:
would assign
Juli
to
month,
3
to
day
and
1986
to
year. The success of literal matches and suppressed assignments
can be determined with the
%n
conversion specification.
Here is an example that checks the success of literal matches:
int i, n1, n2, n3, n4;
n1 = n2 = n3 = n4 = -1;
scanf("%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4);
if (n2 - n1 == 5) puts( "matched BEGIN");
if (n4 - n3 == 3) puts( "matched END"); Here is an example that checks the success of suppressed assignments:
int i, n1, n2;
n1 = n2 = -1;
scanf( "%d %n%*s%n", &i, &n1, &n2);
if (n2 > n1)
printf("successful assignment suppression of %d chars\n", n2-n1); APPLICATION USAGEAfter
scanf()
or
fscanf()
is applied to a stream, the stream becomes byte-oriented (see
orientation(5)). WARNINGSTrailing white space (including a newline) is left
unread unless matched in the control string. Truncation of multi-byte characters may occur if a field width is used
with the conversion character. AUTHORscanf()
was developed by AT&T and HP. STANDARDS CONFORMANCEscanf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C fscanf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C sscanf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C |
Printable version
