setbuf

scanf

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

The scanf( ) function is a general-purpose input routine that reads the stream stdin and stores the information in the variables pointed to in its argument list. It can read all the built-in data types and automatically converts them into the proper internal format.

In C99, format is qualified with restrict.

The control string pointed to by format consists of three classifications of characters:

Format specifiers
Whitespace characters
Nonwhitespace characters

The input format specifiers begin with a % sign and tell scanf( ) what type of data is to be read next. The format specifiers are listed in the following table. For example, %s reads a string while %d reads an integer. The format string is read left to right and the format specifiers are matched, in order, with the arguments that comprise the argument list.

Code	Meaning
%a	Read a floating-point value (C99 only)
%A	Same as %a (C99 only)
%c	Read a single character
%d	Read a decimal integer
%i	Read an integer in either decimal, octal, or hexadecimal format
%e	Read a floating-point number
%E	Same as %e
%f	Read a floating-point number
%F	Same as %f (C99 only)
%g	Read a floating-point number
%G	Same as %g
%o	Read an octal number
%s	Read a string
%x	Read a hexadecimal number
%X	Same as %x
%p	Read a pointer
%n	Receive an integer value equal to the number of characters read so far
%u	Read an unsigned decimal integer
%[ ]	Scan for a set of characters
%%	Read a percent sign

To read a long integer, put an l (ell) in front of the format specifier. To read a short integer, put an h in front of the format specifier. These modifiers can be used with the d, i, o, u, and x format codes.

By default, the a, f, e, and g tell scanf( ) to assign data to a float. If you put an l (ell) in front of one of these specifiers, scanf( ) assigns the data to a double. Using an L tells scanf( ) that the variable receiving the data is a long double.

If you are using a modern compiler that supports the wide-character features added in 1995, then you can use the l modifier with the c format code to indicate a pointer to a wide character of type whcar_t. You can also use the l modifier with the s format code to indicate a pointer to a wide-character string. The l may also be used to modify a scanset to indicate wide characters.

A whitespace character in the format string causes scanf( ) to skip over zero or more whitespace characters in the input stream. A whitespace character is either a space, a tab character, or a newline. In essence, one whitespace character in the control string will cause scanf( ) to read, but not store, any number (including zero) of whitespace characters up to the first nonwhitespace character.

A nonwhitespace character in the format string causes scanf( ) to read and discard a matching character. For example, %d,%d causes scanf( ) to first read an integer, then read and discard a comma, and finally read another integer. If the specified character is not found, scanf( ) will terminate.

All the variables used to receive values through scanf( ) must be passed by their addresses. This means that all arguments must be pointers to the variables.

In the input stream, items must be separated by spaces, tabs, or newlines. Punctuation such as commas, semicolons, and the like do not count as separators. This means that

scanf("%d%d", &r, &c);

will accept an input of 10 20 but fail with 10,20.

An * placed after the % and before the format code will read data of the specified type but suppress its assignment. Thus, the following command:

scanf("%d%*c%d", &x, &y);

given the input 10/20, will put the value 10 into x, discard the divide sign, and give y the value 20.

The format commands can specify a maximum field-length modifier. This is an integer number placed between the % and the format code that limits the number of characters read for any field. For example, if you wish to read no more than 20 characters into address, then you would write the following:

scanf("%20s", address);

If the input stream were greater than 20 characters, a subsequent call to input would begin where this call left off. Input for a field may terminate before the maximum field length is reached if a whitespace is encountered. In this case, scanf( ) moves on to the next field.

Although spaces, tabs, and newlines are used as field separators, when reading a single character, these are read like any other character. For example, given an input stream of x y,

scanf("%c%c%c", &a, &b, &c);

will return with the character x in a, a space in b, and the character y in c.

Remember that any non-format specifiers in the control string—including spaces, tabs, and newlines—will be used to match and discard characters from the input stream. Any character that matches is discarded. For example, given the input stream 10t20,

scanf("%dt%d", &x, &y);

will store 10 in x and 20 in y. The t is discarded because of the t in the control string.

Another feature of scanf( ) is called a scanset. A scanset defines a set of characters that will be read by scanf( ) and assigned to the corresponding character array. A scanset is defined by putting the characters you want to scan for inside square brackets. The beginning square bracket must be prefixed by a percent sign. For example, this scanset tells scanf( ) to read only the characters A, B, and C:

%[ABC]

When a scanset is used, scanf( ) continues to read characters and put them into the corresponding character array until a character that is not in the scanset is encountered. The corresponding variable must be a pointer to a character array. Upon return from scanf( ), the array will contain a null-terminated string comprised of the characters read.

You can specify an inverted set if the first character in the set is a ^. When the ^ is present, it instructs scanf( ) to accept any character that is not defined by the scanset.

For many implementations, you can specify a range using a hyphen. For example, this tells scanf( ) to accept the characters A through Z:

%[A-Z]

One important point to remember is that the scanset is case sensitive. Therefore, if you want to scan for both uppercase and lowercase letters, they must be specified individually.

The scanf( ) function returns a number equal to the number of fields that were successfully assigned values. This number will not include fields that were read but not assigned because the * modifier was used to suppress the assignment. EOF is returned if an error occurs before the first field is assigned.

Format Modifiers Added to scanf( ) by C99

C99 adds several format modifiers to scanf( ): hh, ll, j, z, and t. The hh modifier can be applied to d, i, o, u, x, or n. It specifies that the corresponding argument is a pointer to a signed or unsigned char value. The ll modifier also can be applied to d, i, o, u, x, or n. It specifies that the corresponding argument is a pointer to a signed or unsigned long long int value.

The j format modifier, which applies to d, i, o, u, x, or n, specifies that the matching argument is a pointer to an object of type intmax_t or uintmax_t. These types are declared in <stdint.h> and specify greatest-width integers.

The z format modifier, which applies to d, i, o, u, x, or n, specifies that the matching argument is a pointer to an object of type size_t. This type is declared in <stddef.h> and specifies the result of sizeof.

The t format modifier, which applies to d, i, o, u, x, or n, specifies that the matching argument is a pointer to an object of type ptrdiff_t. This type is declared in <stddef.h> and specifies the difference between two pointers.

Related functions are printf( ) and fscanf( ).