scanf

scanf

Reads formatted data from standard input

#include <stdio.h>
int scanf ( const char * restrict format , ... );

The scanf( ) function reads a sequence of characters from the standard input stream and parses it for the data items specified by the format string. The function then stores the data in the locations addressed by the subsequent pointer arguments.

The ellipsis (...) in the function prototype indicates that scanf( ) takes a variable number of optional arguments. All parameters after those explicitly declared can be considered to be of the type void *, which means that you can pass any type of object pointer to scanf( ) in that position. Each of these pointer arguments must point to a variable whose type agrees with the corresponding conversion specification in the format string. If there are more such arguments than conversion specifiers, the excess arguments are ignored.

Conversion specification syntax

For a general overview of data conversion with scanf( ), see "Formatted Input" in Chapter 13. This section describes the syntax of conversion specifications in the scanf( ) format string in detail. The conversion specifications have the following syntax:

%[*][field width][length modifier]specifier

Before processing each conversion specification in the format string, scanf( ) skips over any whitespace characters in the input stream (except with the conversion specifiers c and [ ], which we will describe in a moment). For each conversion specification, scanf( ) reads one or more characters from the input stream. As soon as scanf( ) reads a character that cannot be interpreted under the current conversion specification, reading is interrupted, as if the first character after the data to be converted had not been read. Then scanf( ) converts the characters that belong to the field, and assigns the result to the variable addressed by the corresponding pointer argument.

If a conversion specification contains an asterisk after the percent sign (%*...), then the result of the conversion is not assigned to a variable, but simply discarded.

The optional field width is a positive integer that specifies the maximum number of characters to read and convert for the given conversion specification.

The length modifier qualifies the conversion specifier to indicate the corresponding argument's type more specifically. Each length modifier value is applicable only to certain conversion specifier values. If they are mismatched, the function's behavior is undefined. The permissible length modifier values and their meaning for the appropriate conversion specifiers are listed in Table 17-8.

Table 17-8. scanf( ) conversion specifier modifiers
Modifier
With conversion specifier
Corresponding argument's type
hh
d, i, o, u, x, X, or n
signed char * or unsigned char *
h
d, i, o, u, x, X, or n
short int * or unsigned short int *
l (ell)
d, i, o, u, x, X, or n
long int * or unsigned long int *
l (ell)
c, s, or [...]
wchar_t *; conversion as by mbrtowc( )
l (ell)
a, A, e, E, f, F, g, or G
double *
ll (two ells)
d, i, o, u, x, X, or n
long long * or unsigned long long *
j
d, i, o, u, x, X, or n
intmax_t * or uintmax_t *
z
d, i, o, u, x, X, or n
size_t * or a pointer to the corresponding signed integer type
t
d, i, o, u, x, X, or n
ptrdiff_t * or a pointer to the corresponding unsigned integer type
L
a, A, e, E, f, F, g, or G
long double *

The conversion specifier indicates the type of the argument and how the input characters are to be interpreted. The corresponding function argument must have a compatible type; otherwise, the behavior of scanf( ) is undefined. The conversion specifier values are listed in Table 17-9.

Table 17-9. scanf( ) conversion specifiers
Conversion specifier
Argument type
Input notation
d
signed int*
Decimal with optional sign
i
signed int*
Decimal, octal, or hexadecimal, with optional sign
u
unsigned int *
Decimal with optional sign
o
unsigned int *
Octal with optional sign
x
unsigned int *
Hexadecimal with optional sign and/or 0x (or 0X) prefix
a, e, f, or g
float * or double *
Floating-point
c
char * or int *
One character, or several if a field width greater than one is specified
s
char *
Consecutive non-whitespace characters
[scanset]
char *
Consecutive characters from the specified set
n
int *
No input read; instead, scanf( ) stores the number of characters read from input so far in the variable addressed by the argument
p
void *
The system's notation for a pointer value; converts inversely as printf( )
%
None
A single percent sign (%); no value stored

For a description of the character sequences that are interpreted as floating-point numbers, including decimal and hexadecimal exponential notation, see "Floating-Point Constants" in Chapter 3.

If you use the conversion specifier c without a field width, it matches one character. If you specify a field width, as in the conversion specification %7c, then scanf( ) reads the specified number of characters, including whitespace characters, and assigns them to successive elements of an array of char addressed by the corresponding pointer argument, but does not append a terminating null character. It is up to you to make sure that the argument points to the first element of an array of sufficient size to accommodate the number of characters indicated by the field width.

If you use the conversion specifier c together with the length modifier l, then scanf( ) reads one or more bytes (according to the specified field width, if any), converting them as it goes from multibyte characters to wide characters in the same way as successive calls to the mbrtowc( ) function would, starting with an mbstate_t object corresponding to the initial parsing state. If you specify a field width, scanf( ) reads the specified number of bytes, and assigns the corresponding wide characters to successive elements of an array of wchar_t addressed by the corresponding pointer argument, but does not append a terminating null wide character ('\0'L). It is up to you to make sure that the argument points to the first element of an array of sufficient size to accommodate the number of wide characters stored.

The conversion specifier s is similar to c, with these exceptions:

scanf( ) with an s specifier stops reading at the first whitespace character, or when it has read the number of bytes indicated by the field length, if specified.
scanf( ) with an s specifier appends a null character (or wide character, if the l modifier is present) to the sequence of characters (or wide characters) stored. The pointer argument must point to the first element of an array that is large enough to accommodate the characters read plus the null character.

The conversion specifier [...] is similar to s, with the following exceptions: rather than matching any sequence of non-whitespace characters, it matches any sequence of the characters in the set that appear between the square brackets, called the scanset. (The scanset may or may not include whitespace characters.) If the first character after the opening bracket is a caret (^), then it is not a member of the scanset, but inverts the meaning of the set of characters that follows; the conversion specifier matches any sequence of the characters that do not appear in the list that follows the caret.

If the first character after the opening bracket (or after the opening bracket and an initial caret) of a [...] specifier is a right bracket (]), then that right bracket is interpreted as a member of the character list that defines the scanset, not as the closing delimiter. If the characters between the brackets (or between the initial caret and the closing bracket) include a hyphen (-) that is neither in the first nor the last position, then it is left up to the given implementation to define whether scanf( ) interprets the hyphen in a special wayfor example, as indicating a range of characters. For example, the conversion specifier %[0-9] may match any sequence of digits, or any sequence of the characters 0, -, and 9or the implementation may define the hyphen in some other way.

The scanf( ) function stops reading the input stream in whichever of the following events occurs first:

The entire format string has been processed.
A matching failure: a non-whitespace character in the input did not match the corresponding position in the format string.
An input failure: no input can be read to match a conversion specification or a non-whitespace character, or an encoding error occurs.

Any non-whitespace character in the format string that is not part of a conversion specification is processed by reading a character from the input stream, and testing for a literal match. If the characters do not match, scanf( ) returns, leaving the input stream as if the mismatched character had not been read.

If there are arguments that have not been assigned a value when scanf( ) returns, they will have been evaluated nonetheless. If there are not enough arguments for the data items converted, the behavior is undefined.

The scanf( ) function returns the number of data items assigned to variables, not counting assignments due to %n conversion specifications. If an input failure occurs before any input item can be converted, scanf( ) returns EOF.

Example

double x, y;
char operation[16] = "";
scanf("%15s%lf%*[^0123456789]%lf", operation, &x, &y);

The format string in this scanf( ) call contains four conversion specifications. Let us assume that a user enters the following sequence of characters when this call occurs:

Divide 1.5e3 by 52.25\n

For the first conversion specification, %15s, scanf( ) reads each character up to the first space, and hence stores the string "Divide", terminated by a null character, in the array operation. After the space, the sequence 1.5e3 matches the conversion specification %lf, and scanf( ) assigns the value 1500.0 to the double variable x. After the next space, each of the characters 'b', 'y', and ' ' (the space) is in the very large scanset of the conversion specification %*[^01234567890]; the first character that does not match is the digit character '5'. Because the conversion specification contains the asterisk, scanf( ) discards the characters read, then reads to the next whitespace character, '\n', for the conversion specification %lf, and assigns the value 52.25 to the variable y.

For another example, see fscanf( ) in this chapter. (fscanf( ) reads a specified file rather than stdin, but is otherwise similar to scanf( ).)

Conversion specification syntax

Table 17-8. scanf( ) conversion specifier modifiers

Table 17-9. scanf( ) conversion specifiers

Example

See Also