[scanf] [format]
[type] [width] [size_prefixes]
|
Routine |
Required header |
|
scanf |
<stdio.h> |
Read formatted data from
the standard input stream.
int scanf( const char *format [,argument]... );
Parameters
format
Format control string.
argument
Optional arguments.
Return
Value
Returns the number of
fields successfully converted and assigned; the return value does not include
fields that were read but not assigned. A return value of 0 indicates that no fields
were assigned. The return value is EOF for an error or if the
end-of-file character or the end-of-string character is encountered in the
first attempt to read a character.
Remarks
The scanf
function reads data from the standard input stream stdin
and writes the data into the location given by argument. Each argument
must be a pointer to a variable of a type that corresponds to a type specifier in format. If copying takes place between
strings that overlap, the behavior is undefined.
wscanf is a wide-character
version of scanf; the format argument
to wscanf is a wide-character string. wscanf and scanf
behave identically otherwise.
[scanf]
[format] [type] [width] [size_prefixes]
Format
Specification Fields: scanf
and wscanf Functions
A format specification
has the following form:
%[*] [width] [{h | l | I64 | L}]type
The format
argument specifies the interpretation of the input and can contain one or more
of the following:
The format is read from
left to right. Characters outside format specifications are expected to match
the sequence of characters in stdin; the
matching characters in stdin are scanned but
not stored. If a character in stdin conflicts
with the format specification, scanf
terminates, and the character is left in stdin
as if it had not been read.
When the first format
specification is encountered, the value of the first input field is converted
according to this specification and stored in the location that is specified by
the first argument. The second format specification causes the second
input field to be converted and stored in the second argument, and so on
through the end of the format string.
An input field is
defined as all characters up to the first white-space character (space, tab, or
newline), or up to the first character that cannot be
converted according to the format specification, or until the field width (if
specified) is reached. If there are too many arguments for the given
specifications, the extra arguments are evaluated but ignored. The results are
unpredictable if there are not enough arguments for the format specification.
Each field of the format
specification is a single character or a number signifying a particular format
option. The type character, which appears after the last optional format
field, determines whether the input field is interpreted as a character, a
string, or a number.
The simplest format
specification contains only the percent sign and a type character (for
example, %s). If a percent sign (%)
is followed by a character that has no meaning as a format-control character,
that character and the following characters (up to the next percent sign) are
treated as an ordinary sequence of characters, that is, a sequence of
characters that must match the input. For example, to specify that a
percent-sign character is to be input, use %%.
An asterisk (*)
following the percent sign suppresses assignment of the next input field, which
is interpreted as a field of the specified type. The field is scanned but not
stored.
[scanf] [format]
[type] [width] [size_prefixes]
scanf
Type Field Characters
The type character
is the only required format field; it appears after any optional format fields.
The type character determines whether the associated argument is
interpreted as a character, string, or number.
Type
Characters for scanf functions
|
Character |
Type of input expected |
Type of argument |
|
c |
When
used with scanf functions, specifies
single-byte character; when used with wscanf
functions, specifies wide character. White-space characters that are
ordinarily skipped are read when c is specified. To read next
non–white-space single-byte character, use %1s; to read next
non–white-space wide character, use %1ws. |
Pointer
to char when used with scanf
functions, pointer to wchar_t when used with
wscanf functions. |
|
C |
When
used with scanf functions, specifies wide
character; when used with wscanf functions,
specifies single-byte character. White-space characters that are ordinarily
skipped are read when C is specified. To read next non–white-space
single-byte character, use %1s; to read next non–white-space wide
character, use %1ws. |
Pointer
to wchar_t when used with scanf functions, pointer to char when used
with wscanf functions. |
|
d |
Decimal
integer. |
Pointer
to int. |
|
i |
Decimal,
hexadecimal, or octal integer. |
Pointer
to int. |
|
o |
Octal
integer. |
Pointer
to int. |
|
u |
Unsigned
decimal integer. |
Pointer
to unsigned int. |
|
x |
Hexadecimal
integer. |
Pointer
to int. |
|
e, E, f, g,
G |
Floating-point
value consisting of optional sign (+ or –), series of one or more decimal digits
containing decimal point, and optional exponent ("e" or
"E") followed by an optionally signed integer value. |
Pointer
to float. |
|
n |
No
input read from stream or buffer. |
Pointer
to int, into which is stored number of
characters successfully read from stream or buffer up to that point in
current call to scanf functions or wscanf functions. |
|
s |
String,
up to first white-space character (space, tab or newline).
To read strings not delimited by space characters, use set of square brackets
([ ]), as discussed after the Size Prefixes
for scanf and wscanf
Format-Type Specifiers table. |
When
used with scanf functions, signifies
single-byte character array; when used with wscanf
functions, signifies wide-character array. In either case, character array
must be large enough for input field plus terminating null character, which
is automatically appended. |
|
S |
String,
up to first white-space character (space, tab or newline).
To read strings not delimited by space characters, use set of square brackets
([ ]), as discussed preceding this table. |
When
used with scanf functions, signifies
wide-character array; when used with wscanf functions,
signifies single-byte–character array. In either case, character array must
be large enough for input field plus terminating null character, which is
automatically appended. |
The types c, C,
s, and S are Microsoft extensions and are not ANSI compatible.
Thus, to read
single-byte or wide characters with scanf
functions and wscanf functions, use format specifiers as follows.
|
To read character as |
Use this function |
With these format specifiers |
|
single
byte |
scanf functions |
c, hc,
or hC |
|
single
byte |
wscanf functions |
C, hc,
or hC |
|
wide |
wscanf functions |
c, lc,
or lC |
|
wide |
scanf functions |
C, lc,
or lC |
To scan strings with scanf functions, and wscanf
functions, use the prefixes h and l analogously with
format type-specifiers s and S.
[scanf] [format] [type] [width] [size_prefixes]
scanf
Width Specification
width is a positive decimal
integer controlling the maximum number of characters to be read from stdin. No more than width characters are
converted and stored at the corresponding argument. Fewer than width
characters may be read if a white-space character (space, tab, or newline) or a character that cannot be converted according
to the given format occurs before width is reached.
The optional prefixes h,
l, I64, and L indicate the size of the argument
(long or short, single-byte character or wide character, depending upon the
type character that they modify). These format-specification characters are
used with type characters in scanf or wscanf functions to specify interpretation of
arguments as shown in the following table. The type prefixes h, l,
I64, and L are Microsoft extensions and are not ANSI compatible.
The type characters and their meanings are described in the Type
Characters for scanf functions table.
Note The h,
l, and L prefixes are Microsoft extensions when used with data of
type char.
Size
Prefixes for scanf and wscanf
Format-Type Specifiers
|
To specify |
Use prefix |
With type specifier |
|
double |
l |
e, E, f, g,
or G |
|
long
double (same
as double) |
L |
e, E, f, g,
or G |
|
long
int |
l |
d, i,
o, x, or X |
|
long
unsigned int |
l |
u |
|
short
int |
h |
d, i,
o, x, or X |
|
short
unsigned int |
h |
u |
|
__int64 |
I64 |
d, i,
o, u, x, or X |
|
Single-byte
character with scanf |
h |
c
or C |
|
Single-byte
character with wscanf |
h |
c or C |
|
Wide
character with scanf |
l |
c or C |
|
Wide
character with wscanf |
l |
c, or C |
|
Single-byte
– character string with scanf |
h |
s or S |
|
Single-byte
– character string with wscanf |
h |
s or S |
|
Wide-character
string with scanf |
l |
s or S |
|
Wide-character
string with wscanf |
l |
s or S |
The following examples
use h and l with scanf functions
and wscanf functions:
scanf( "%ls", &x );
// Read a wide-character string
wscanf( "%lC", &x );
// Read a single-byte character
To read strings not
delimited by space characters, a set of characters in brackets ([ ]) can
be substituted for the s (string) type character. The corresponding
input field is read up to the first character that does not appear in the
bracketed character set. If the first character in the set is a caret (^),
the effect is reversed: The input field is read up to the first character that
does appear in the rest of the character set.
Note that %[a-z]
and %[z-a] are interpreted as equivalent to %[abcde...z].
This is a common scanf function extension, but
note that the ANSI standard does not require it.
To store a string
without storing a terminating null character ('\0'), use the specification %nc where n is a decimal integer. In
this case, the c type character indicates that the argument is a pointer
to a character array. The next n characters are read from the input
stream into the specified location, and no null character ('\0') is appended.
If n is not specified, its default value is 1.
The scanf
function scans each input field, character by character. It may stop reading a
particular input field before it reaches a space character for a variety of
reasons:
For whatever reason,
when the scanf function stops reading an input
field, the next input field is considered to begin at the first unread
character. The conflicting character, if there is one, is considered unread and
is the first character of the next input field or the first character in subsequent
read operations on stdin.
[scanf] [format]
[type] [width] [size_prefixes]
Example
/* SCANF.C: This program uses the scanf and wscanf functions
* to read formatted input.
*/
#include <stdio.h>
void main( void )
{
int i, result;
float fp;
char
c, s[81];
wchar_t wc, ws[81];
printf( "\n\nEnter an int, a float, two chars
and two strings\n");
result = scanf(
"%d %f %c %C %s %S", &i, &fp, &c, &wc, s, ws );
printf( "\nThe number of fields input is %d\n", result );
printf( "The
contents are: %d %f %c %C %s %S\n", i, fp, c, wc, s, ws);
wprintf(
L"\n\nEnter an int, a
float, two chars and two strings\n");
result = wscanf( L"%d %f %hc %lc %S %ls", &i, &fp, &c, &wc, s, ws );
wprintf( L"\nThe number of fields input is %d\n", result );
wprintf( L"The contents are: %d %f %C %c %hs
%s\n", i, fp, c, wc, s, ws);
}
Output
Enter an int, a float, two chars and two strings
71
98.6
h
z
Byte characters
The number of
fields input is 6
The contents are:
71 98.599998 h z Byte characters
Enter an int, a float, two chars and two strings
36
92.3
y
n
Wide characters
The number of
fields input is 6
The contents are:
456 92.300003 y n Wide characters
[scanf] [format]
[type] [width] [size_prefixes]
Reference:
Taken from MSDN Run-time
reference Library.