scanf

Description

Reads formatted data from the standard input stream.

#include <stdio.h>

int scanf( const char *format[[,argument]]... );

Remarks

The scanf function reads data from the standard input stream stdin into the locations given by argument. Each argument must be a pointer to a variable with a type that corresponds to a type specifier in format. The format controls the interpretation of the input fields. The format can contain one or more of the following:

White-space characters: blank (' '); tab (\t); or newline (\n). A white-space character causes scanf to read, but not store, all consecutive white-space characters in the input up to the next non-white-space character. One white-space character in the format matches any number (including 0) and combination of white-space characters in the input.

Non-white-space characters, except for the percent sign (%). A non-white-space character causes scanf to read, but not store, a matching non-white-space character. If the next character in stdin does not match, scanf terminates.

Format specifications, introduced by the percent sign (%). A format specification causes scanf to read and convert characters in the input into values of a specified type. The value is assigned to an argument in the argument list.

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. 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.

A format specification has the following form:

%[[*]] [[width]] [[{F | N}]] [[{h | l}]]type

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).

Each field of the format specification is discussed in detail below. 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.

The 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 F and N prefixes allow the user to specify whether the argument is far or near, respectively. F should be prefixed to an argument pointing to a far object, while N should be prefixed to an argument pointing to a near object. Note also that the F and N prefixes are not part of the ANSI definition for scanf, but are instead Microsoft extensions, which should not be used when ANSI portability is desired.

The optional prefix l indicates that the long version of the following type is to be used, while the prefix h indicates that the short version is to be used. The corresponding argument should point to a long or double object (with the l character) or a short object (with the h character). The l and h modifiers can be used with the d, i, n, o, x, and u type characters. The l modifier can also be used with the e, f, and g type characters. The l and h modifiers are ignored if specified for any other type.

For scanf, N and F refer to the “distance” to the object being read in (near or far) and h and l refer to the “size” of the object being read in (16-bit short or 32-bit long). The list below clarifies this use of N, F, l, and h:

The type characters and their meanings are described in Table R.5.

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 extension, but note that it is not required by the ANSI standard.

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, the default value for it 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: the specified width has been reached; the next character cannot be converted as specified; the next character conflicts with a character in the control string that it is supposed to match; or the next character fails to appear in a given character set. For whatever reason, when scanf 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.

Table R.5 Type Characters for scanf

1 Since the input for a %x format specifier is always interpreted as a hexadecimal number, the input should not include a leading 0x. (If 0x is included, the 0 is interpreted as a hexadecimal input value.)

Return Value

The scanf function returns the number of fields that were successfully converted and assigned. The return value may be less than the number requested in the call to scanf. The return value does not include fields that were read but not assigned.

The return value is EOF if the end-of-file or end-of-string is encountered in the first attempt to read a character.

Compatibility

Standards:ANSI, UNIX

16-Bit:DOS, QWIN

32-Bit:DOS32X

See Also

fscanf, printf, sscanf, vfprintf, vprintf, vsprintf

Example

/* SCANF.C: This program receives formatted input using scanf. */

#include <stdio.h>

void main( void )

{

int i;

float fp;

char c, s[81];

int result;

printf( "Enter an integer, a floating-point number, "

"a character and a string:\n" );

result = scanf( "%d %f %c %s", &i, &fp, &c, s );

printf( "\nThe number of fields input is %d\n", result );

printf( "The contents are: %d %f %c %s\n", i, fp, c, s );

}

Output

Enter an integer, a floating-point number, a character and a string:

71

98.6

h

White space stops input

The number of fields input is 4

The contents are: 71 98.599998 h White