### scanf -- Read Data

Format

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

Language Level: ANSI, ANSI 93, POSIX, XPG4, Extension
scanf reads data from the standard input stream stdin into the locations given by each entry in argument-list. Each argument must be a pointer to a variable with a type that corresponds to a type specifier in format-string. The format-string controls the interpretation of the input fields, and is a multibyte character string.

The format-string can contain one or more of the following:

- White-space characters, as specified by isspace (such as blanks and new-line characters). A white-space character causes scanf to read, but not to store, all consecutive white-space characters in the input up to the next character that is not white space. One white-space character in format-string matches any combination of white-space characters in the input.
- Characters that are not white space, except for the percent sign character (%). A non-white-space character causes scanf to read, but not to store, a matching non-white-space character. If the next character in stdin does not match, scanf ends.
- 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.

scanf reads format-string from left to right. Characters outside of format specifications are expected to match the sequence of characters in stdin; the matched characters in stdin are scanned but not stored. If a character in stdin conflicts with format-string, scanf ends. The conflicting character is left in stdin as if it had not been read.

When the first format specification is found, the value of the first input field is converted according to the format specification and stored in the location specified by the first entry in argument-list. The second format specification converts the second input field and stores it in the second entry in argument-list, and so on through the end of format-string.

Conversions can be applied to the nth argument after the format-string in the argument-list, rather than to the next unused argument. In this case, the conversion character % is replaced by the sequence %n$, where n is a decimal integer in the range [1, {NL_ARGMAX}], (NL_ARGMAX is defined in <limits.h>), giving the position of the argument in the argument-list. This feature provides for the definition of format strings that select arguments in an order appropriate to specific languages. In format strings containing the %n$ form of conversion specifications, numbered arguments in the argument-list can be referenced from the format-string more than once.

The format-string can contain either form of a conversion specfication, that is % or %n$, but the two forms cannot normally be mixed within a single format-string. The only exception to this is that %% or %* can be mixed with the %n$ form.

An input field is defined as all characters up to the first white-space character (space, tab, or new line), up to the first character that cannot be converted according to the format specification, or until the field width is reached, whichever comes first. If there are too many arguments for the format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for the format specifications.

On OS/2 and Windows, a format specification has the following form:

Each field of the format specification is a single character or a number signifying a particular format option. The "scanf Format Type Fields"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).

The fields of the format specification are discussed in "scanf Format Specification Fields" and "scanf Format Type Fields". If a percent sign (%) is followed by a character that has no meaning as a format control character, that character and 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 a percent-sign character, use %%.

scanf Format Specification Fields
The scanf format specification fields are described below. 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 are read if a white-space character (space, tab, or new line), or a character that cannot be converted according to the given format occurs before width is reached.

The optional prefix l shows that you use the long long version of the following type, while the prefix h indicates that the short version is to be used. The optional prefix l, and the optional prefix L, shows that you use the long version of the following type. The corresponding argument should point to a long longobject (for the ll character0, to a long or double object (for the l character), a long double object (for the L character), or a short object (with the h character). The l, ll, and h modifiers can be used with the d, i, o, x, and u type characters. The l modifier can also be used with the e, f, and g type characters. The L modifier can be used with the e, f and g type characters. The l and h modifiers are ignored if specified for any other type. Note that the l modifier is also used with the c and s characters to indicate a multibyte character or string.

scanf Format Type Fields
The type characters and their meanings are in the following table:

Character | Type of Input Expected | Type of Argument
--- | --- | ---
d | Decimal integer. | Pointer to int.
o | Octal integer. | Pointer to unsigned int.
x, X | Hexadecimal integer. | Pointer to unsigned int.
i | Decimal, hexadecimal, or octal integer. | Pointer to int.
u | Unsigned decimal integer. | Pointer to unsigned int.
e, f, g E, G | Floating-point value consisting of an optional sign (+ or -); a series of one or more decimal digits possibly containing a decimal point; and an optional exponent (e or E) followed by a possibly signed integer value. | Pointer to float.
c | Character; white-space characters that are ordinarily skipped are read when c is specified. | Pointer to char large enough for input field.
lc or C (See Note below.) | Multibyte characters. The multibyte characters are converted to wide characters as if by a call to mbrtowc. The field width specifies the number of wide characters matched; if no width is specified, one character is matched. | Pointer to wchart large enough for input field.
s | String. | Pointer to character array large enough for input field plus a terminating null character (\0), which is automatically appended.
ls or S (See Note below.) | Multibyte string. None of the characters can be single-byte white-space characters (as specified by the isspace function). Each multibyte character in the sequence is converted to a wide character as if by a call to mbrtowc. | Pointer to wchar_t array large enough for the input field and the terminating null wide character (L\0), which is added automatically.
n | No input read from stream or buffer. | Pointer to int, into which is stored the number of characters successfully read from the stream or buffer up to that point in the call to scanf.
p | Pointer to void converted to series of characters. | Pointer to void.

Note: IBM C and C++ Compilers supports the type characters %lc and %ls in accordance with ANSI 93, and supports %C and %S to comply with XPG4.

To read strings not delimited by space characters, substitute a set of characters in brackets ([ ]) 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.

To store a string without storing an ending null character (\0), use the specification %ac, where a is a decimal integer. In this instance, the c type character means that the argument is a pointer to a character array. The next a characters are read from the input stream into the specified location, and no null character is added.

The input for a %x format specifier is interpreted as a hexadecimal number.

scanf scans each input field character by character. It might stop reading a particular input field either before it reaches a space character, when the specified width is reached, or when the next character cannot be converted as specified. When a conflict occurs between the specification and the input character, the next input field begins at the first unread character. The conflicting character, if there was one, is considered unread and is the first character of the next input field or the first character in subsequent read operations on stdin.

Return Value
scanf returns the number of fields that were successfully converted and assigned. The return value does not include fields that were read but not assigned.

The return value is EOF for an attempt to read at end-of-file if no conversion was performed. A return value of 0 means that no fields were assigned.

Examples

_cscanf -- Read Data from Keyboard
fscanf -- Read Data from a Stream
printf -- Print Formatted Characters
sscanf -- Read Data from Buffer
<limits.h>
<stdio.h>