SCANF(3) | Library Functions Manual | SCANF(3) |
scanf
, fscanf
,
sscanf
, vscanf
,
vsscanf
, vfscanf
—
input format conversion
#include
<stdio.h>
int
scanf
(const
char *format,
...);
int
fscanf
(FILE
*stream, const char
*format, ...);
int
sscanf
(const
char *str, const char
*format, ...);
#include
<stdarg.h>
int
vscanf
(const
char *format, va_list
ap);
int
vsscanf
(const
char *str, const char
*format, va_list
ap);
int
vfscanf
(FILE
*stream, const char
*format, va_list
ap);
The
scanf
()
family of functions read input according to the given
format as described below. This format may contain
“conversion specifiers”; the results of such conversions, if
any, are stored through a set of pointer arguments.
The
scanf
()
function reads input from the standard input stream
stdin,
fscanf
()
reads input from the supplied stream pointer stream,
and
sscanf
()
reads its input from the character string pointed to by
str.
The
vfscanf
()
function is analogous to
vfprintf(3) and reads input
from the stream pointer stream using a variable
argument list of pointers (see
stdarg(3)). The
vscanf
()
function scans a variable argument list from the standard input and the
vsscanf
()
function scans it from a string; these are analogous to the
vprintf
()
and
vsprintf
()
functions, respectively.
Each successive
pointer argument
must correspond properly with each successive conversion specifier (but see
the *
conversion below). All conversions are
introduced by the %
(percent sign) character. The
format string may also contain other characters.
Whitespace (such as blanks, tabs, or newlines) in the
format string match any amount of whitespace,
including none, in the input. Everything else matches only itself. Scanning
stops when an input character does not match such a format character.
Scanning also stops when an input conversion cannot be made (see below).
Following the %
character, introducing a
conversion, there may be a number of
flag
characters, as follows:
*
hh
dioux
or n
and the next pointer is a pointer to a
char (rather than int).h
dioux
or n
and the next pointer is a pointer to a
short int (rather than
int).l
(ell)dioux
or n
and the next
pointer is a pointer to a long int (rather than
int), or that the conversion will be one of
efg
and the next pointer is a pointer to
double (rather than float), or
that the conversion will be one of sc[
.
If the conversion is one of
sc[
the expected conversion input is a multibyte
character sequence. Each multibyte character in the sequence is
converted with a call to the
mbrtowc
()
function. The field width specifies the maximum amount of bytes read
from the multibyte character sequence and passed to
mbrtowc
() for conversion. The next pointer is a
pointer to a wchar_t wide-character buffer large
enough to accept the converted input sequence including the terminating
NUL wide character which will be added automatically.
ll
(ell ell)dioux
or n
and the next pointer is a pointer to a
long long int (rather than
int).L
efg
and the next pointer is a pointer to long
double.j
dioux
or n
and the next pointer is a pointer to an
intmax_t (rather than
int).t
dioux
or n
and the next pointer is a pointer to a
ptrdiff_t (rather than
int).z
dioux
or n
and the next pointer is a pointer to a
size_t (rather than int).q
dioux
or n
and the next
pointer is a pointer to a long long int (rather than
int).In addition to these flags, there may be an optional maximum field
width, expressed as a decimal integer, between the %
and the conversion. If no width is given, a default of
“infinity” is used (with one exception, below); otherwise at
most this many characters are scanned in processing the conversion. Before
conversion begins, most conversions skip whitespace; this whitespace is not
counted against the field width.
The following conversions are available:
%
%
’. That is,
“%%
” in the format string matches a
single input ‘%
’ character. No
conversion is done, and assignment does not occur.d
D
ld
; this exists only for backwards
compatibility.i
0x
’ or
‘0X
’, in base 8 if it begins with
‘0
’, and in base 10 otherwise. Only
characters that correspond to the base are used.o
O
lo
; this exists for backwards
compatibility.u
xX
eE
f
.fF
gG
f
.aA
f
.s
c
[
The string is to be made up of characters in (or
not in) a particular set; the set is defined by the characters between
the open bracket [
character and a close bracket
]
character. The set
excludes
those characters if the first character after the open bracket is a
circumflex ^
. To include a close bracket in the
set, make it the first character after the open bracket or the
circumflex; any other position will end the set. The hyphen character
-
is also special; when placed between two other
characters, it adds all intervening characters to the set. To include a
hyphen, make it the last character before the final close bracket.
For instance, ‘[^]0-9-]
’
means the set “everything except close bracket, zero through
nine, and hyphen”. The string ends with the appearance of a
character not in (or, with a circumflex, in) the set or when the field
width runs out.
p
%p
’ in
printf(3)); the next
pointer must be a pointer to void.n
*
flag.For backwards compatibility, other conversion characters (except
‘\0
’) are taken as if they were
‘%d
’ or, if uppercase,
‘%ld
’, and a `conversion' of
‘%\0
’ causes an immediate return of
EOF
.
These functions return the number of input items assigned, which
can be fewer than provided for, or even zero, in the event of a matching
failure. Zero indicates that, while there was input available, no
conversions were assigned; typically this is due to an invalid input
character, such as an alphabetic character for a
‘%d
’ conversion. The value
EOF
is returned if an input failure, such as an
end-of-file, occurs before any conversion. If an error or end-of-file occurs
after conversion has begun, the number of conversions which were
successfully completed is returned.
getc(3), mbrtowc(3), printf(3), strtod(3), strtol(3), strtoul(3)
The functions fscanf
(),
scanf
(), and sscanf
()
conform to ANSI X3.159-1989
(“ANSI C89”).
The functions scanf
(),
fscanf
(), and sscanf
() first
appeared in Version 7 AT&T UNIX, and
vscanf
(), vsscanf
(), and
vfscanf
() in
4.3BSD-Reno.
Numerical strings are truncated to 512 characters; for example,
%f
and %d
are implicitly
%512f
and %512d
.
July 17, 2013 | OpenBSD-6.1 |