Synopsis
int scanf(const char *format,
...);
Description
scanf reads input from the standard input stream under control
of the string pointed to by format that specifies the admissible
input sequences and how they are to be converted for assignment, using
subsequent arguments as pointers to the objects to receive the converted
input.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
scanf returns the value of the macro EOF if an input failure occurs
before any conversion. Otherwise, scanf returns the number of input
items assigned, which can be fewer than provided for, or even zero, in the
event of an early matching failure.
Formatted input control strings
The format is composed of zero or more directives: one or more white-space
characters, an ordinary character (neither % nor a white-space
character), or a conversion specification.
Each conversion specification is introduced by the character %.
After the %, the following appear in sequence:
- An optional assignment-suppressing character *.
- An optional nonzero decimal integer that specifies the maximum field width
(in characters).
- An optional length modifier that specifies the size of the receiving object.
- A conversion specifier character that specifies the type of conversion
to be applied.
The formatted input function executes each directive of the format in turn.
If a directive fails, the function returns. Failures are described as input
failures (because of the occurrence of an encoding error or the unavailability
of input characters), or matching failures (because of inappropriate input).
A directive composed of white-space character(s) is executed by reading input
up to the first non-white-space character (which remains unread), or until no
more characters can be read.
A directive that is an ordinary character is executed by reading the next characters
of the stream. If any of those characters differ from the ones composing the
directive, the directive fails and the differing and subsequent characters remain
unread. Similarly, if end-of-file, an encoding error, or a read error prevents
a character from being read, the directive fails.
A directive that is a conversion specification defines a set of matching input
sequences, as described below for each specifier. A conversion specification
is executed in the following steps:
- Input white-space characters (as specified by the isspace function)
are skipped, unless the specification includes a [, c, or n
specifier.
- An input item is read from the stream, unless the specification includes
an n specifier. An input item is defined as the longest sequence of input
characters which does not exceed any specified field width and which is, or
is a prefix of, a matching input sequence. The first character, if any, after
the input item remains unread. If the length of the input item is zero, the
execution of the directive fails; this condition is a matching failure unless
end-of-file, an encoding error, or a read error prevented input from the stream,
in which case it is an input failure.
- Except in the case of a % specifier, the
input item (or, in the case of a %n directive, the count of input characters)
is converted to a type appropriate to the conversion specifier. If the input
item is not a matching sequence, the execution of the directive fails: this
condition is a matching failure. Unless assignment suppression was indicated
by a *, the result of the conversion is
placed in the object pointed to by the first argument following the format
argument that has not already received a conversion result. If this object
does not have an appropriate type, or if the result of the conversion cannot
be represented in the object, the behavior is undefined.
Length modifiers
The length modifiers and their meanings are:
- ‘hh’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, ‘X’,
or ‘n’ conversion specifier applies to an argument with type pointer
to signed char or pointer to unsigned char.
- ‘h’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, ‘X’,
or ‘n’ conversion specifier applies to an argument with type pointer
to short int or unsigned short int.
- ‘l’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, ‘X’,
or ‘n’ conversion specifier applies to an argument with type pointer
to long int or unsigned long int; that a following ‘e’, ‘E’,
‘f’, ‘F’, ‘g’, or ‘G’ conversion specifier applies to an argument
with type pointer to double. Some library variants do not
support the ‘l’ length modifier in order to reduce code and data space
requirements; please ensure that you have selected the correct library in
the Printf Integer Support property of the project if you use this
length modifier.
- ‘ll’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, ‘X’,
or ‘n’ conversion specifier applies to an argument with type pointer to
long long int or unsigned long long int. Some library
variants do not support the ‘ll’ length modifier in order to reduce code
and data space requirements; please ensure that you have selected the correct
library in the Printf Integer Support property of the project if you use
this length modifier.
If a length modifier appears with any conversion specifier other than as specified
above, the behavior is undefined. Note that the C99 length modifiers ‘j’,
‘z’, ‘t’, and ‘L’ are not supported.
Conversion specifiers
- ‘d’
- Matches an optionally signed decimal integer, whose format is the same as
expected for the subject sequence of the strtol function with the value
10 for the base argument. The corresponding argument must be a pointer
to signed integer.
- ‘i’
- Matches an optionally signed integer, whose format is the same as expected
for the subject sequence of the strtol function with the value zero
for the base argument. The corresponding argument must be a pointer
to signed integer.
- ‘o’
- Matches an optionally signed octal integer, whose format is the same as
expected for the subject sequence of the strtol function with the value
18 for the base argument. The corresponding argument must be a pointer
to signed integer.
- ‘u’
- Matches an optionally signed decimal integer, whose format is the same as
expected for the subject sequence of the strtoul function with the
value 10 for the base argument. The corresponding argument must be
a pointer to unsigned integer.
- ‘x’
- Matches an optionally signed hexadecimal integer, whose format is the same
as expected for the subject sequence of the strtoul function with the
value 16 for the base argument. The corresponding argument must be
a pointer to unsigned integer.
- ‘e’, ‘f’, ‘g’
- Matches an optionally signed floating-point number whose format is the same
as expected for the subject sequence of the strtod function. The corresponding
argument shall be a pointer to floating. Some library variants
do not support the ‘e’, ‘f’ and ‘F’ conversion specifiers in order to
reduce code and data space requirements; please ensure that you have selected
the correct library in the Scanf Floating Point Support property of
the project if you use these conversion specifiers.
- ‘c’
- Matches a sequence of characters of exactly the number specified by the
field width (one if no field width is present in the directive). The corresponding
argument must be a pointer to the initial element of a character array large
enough to accept the sequence. No null character is added.
- ‘s’
- Matches a sequence of non-white-space characters The corresponding argument
must be a pointer to the initial element of a character array large enough
to accept the sequence and a terminating null character, which will be added
automatically.
- ‘[’
- Matches a nonempty sequence of characters from a set of expected characters
(the scanset). The corresponding argument must be a pointer to the
initial element of a character array large enough to accept the sequence and
a terminating null character, which will be added automatically. The conversion
specifier includes all subsequent characters in the format string, up to and
including the matching right bracket ‘]’. The characters between the brackets
(the scanlist) compose the scanset, unless the character after the left
bracket is a circumflex ‘^’, in which case the scanset contains all characters
that do not appear in the scanlist between the circumflex and the right bracket.
If the conversion specifier begins with ‘[]’ or‘[^]’,
the right bracket character is in the scanlist and the next following right
bracket character is the matching right bracket that ends the specification;
otherwise the first following right bracket character is the one that ends
the specification. If a ‘-’ character is in
the scanlist and is not the first, nor the second where the first character
is a ‘^’, nor the last character, it is treated
as a member of the scanset. Some library variants do not support
the ‘[’ conversion specifier in order to reduce
code and data space requirements; please ensure that you have selected the
correct library in the Scanf Classes Supported property of the project
if you use this conversion specifier.
- ‘p’
- Reads a sequence output by the corresponding ‘%p’
formatted output conversion. The corresponding argument must be a pointer
to a pointer to void.
- ‘n’
- No input is consumed. The corresponding argument shall be a pointer to signed
integer into which is to be written the number of characters read from the
input stream so far by this call to the formatted input function. Execution
of a ‘%n’ directive does not increment the
assignment count returned at the completion of execution of the fscanf function.
No argument is converted, but one is consumed. If the conversion specification
includes an assignment-suppressing character or a field width, the behavior
is undefined.
- ‘%’
- Matches a single ‘%’ character; no conversion
or assignment occurs.
Note that the C99 width modifier ‘l’ used in conjunction with the
‘c’, ‘s’, and ‘[’ conversion specifiers is not supported and nor
are the conversion specifiers ‘a’ and ‘A’.