SCANF - formatted input conversion on "stdin".

(ANSI Standard)

Usage:

#include <stdio.h>
ret = scanf( format [, p1, p2, ...] );

Where:

const char *format;: is a format string as described below.
p1, p2, p3, ...: are pointers to various data types.
int ret;: is the number of matching data items that were read in. This may be zero if the first data item found does not match the type that was expected. If an error or end of file occurs before the first item could be read in, EOF is returned.

Description:

"scanf" reads input from "stdin" and assigns it to the areas of memory pointed to by the pointers "p1", "p2", and so on. The string pointed to by "format" indicates how to interpret the characters being read in. For example, the format string tells whether ASCII digits should be treated as ASCII character data or converted as part of an integer.

The format string usually contains conversion specifications that are used to control the interpretation of input data. The format string may contain any of the following.

Blanks, tabs, or new-lines to match white space in the input.
An ordinary character which must match the next character in the input.
A conversion specification consisting of the character %, an optional assignment-suppressing character *, an optional numerical maximum field width, and a conversion character.

A conversion specification tells the scanning function how to interpret or convert the next input field. The result is placed in the variable pointed to by the corresponding argument, unless this assignment is suppressed by including a * in the conversion specification. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width limit (if specified) is reached.

The conversion character following the % indicates how to interpret the input field. The corresponding pointer must point to an argument of an appropriate type. The following conversion characters are recognized.

%

The sequence %% stands for the character '%'.

a

A floating point number in hexadecimal format is expected, and the corresponding argument should be a pointer to "float". For more information on the way that floating point numbers are represented in hexadecimal format, see the description of "%a" in "expl c lib printf".

c

A single ASCII character is expected, and the corresponding argument should be a character pointer. If a field width is given, the corresponding argument should refer to a character array, into which the indicated number of characters will be read. NOTE: when reading an ASCII character with this construct, "scanf" does NOT skip over leading white space. If you want to skip over white space, use the sequence "%1s" which skips white space, then obtains an ASCII character string one character long. In this case, the memory location that will receive the input character should be big enough to hold TWO characters, since "scanf" puts the usual \0 on the end of the one-character string.

d

A (possibly signed) decimal integer is expected, and the corresponding argument should be an integer pointer.

e or f

A floating point number is expected, and the corresponding argument should be a pointer to float. The next input field is converted accordingly and assigned to the area in memory pointed to by this pointer. The format for floating point numbers is a (possibly signed) string of digits possibly containing a decimal point, followed by an optional exponent field consisting of an 'E' or 'e' followed by a (possibly signed) integer.

n

Does not consume any input. The corresponding argument should be a pointer to a signed integer variable. "scanf" assigns this variable the number of characters that have been read so far from the input stream. This operation does not increase the assignment count that "scanf" returns. You may not specify a field width for "%n".

o

An octal integer is expected, and the corresponding argument should be an integer pointer.

s

A character string is expected. The corresponding argument should be a character pointer pointing to an array of characters large enough to hold the string and a terminating '\0'. The input routine adds the '\0' to terminate the string once it finds a space character or a new-line.

x

A hexadecimal integer is expected, and the corresponding argument should be an integer pointer.

[

The left square bracket indicates a string not to be delimited by white space. The bracket is followed by a set of characters and a right square bracket. The characters between the brackets define a set of characters making up the string. If the first character is not a circumflex (^), the input field consists of all subsequent input characters until the function finds a character not in the character set within the brackets. For example,

%[0123456789]

will gather characters until it finds a character that is not a digit. If the first character inside the square brackets IS a circumflex, the input field consists of all subsequent input characters until the function finds a character that IS in the bracketed character set. Thus

%[^0123456789]

will gather characters until it finds a digit. The corresponding argument must point to a character array.

The conversion characters "d", "i", and "n" may be preceded by an "l" (the letter ell) to indicate that the corresponding argument contains a pointer to a "long int" instead of just "int".
The conversion characters "d", "i", and "n" may be preceded by an "h" to indicate that the corresponding argument contains a pointer to a "short int" instead of just "int".
The conversion characters "d", "i", and "n" may be preceded by an "hh" to indicate that the corresponding argument contains a pointer to a "signed char" instead of just "int".
The conversion characters "o", "u", and "x" may be preceded by an "l" (the letter ell) to indicate that the corresponding argument contains a pointer to an "unsigned long" instead of "unsigned int".
The conversion characters "o", "u", and "x" may be preceded by an "h" to indicate that the corresponding argument contains a pointer to an "unsigned short" instead of "unsigned int".
The conversion characters "o", "u", and "x" may be preceded by an "hh" to indicate that the corresponding argument contains a pointer to an "unsigned char" instead of "unsigned int".
The conversion characters "a", "e", and "f" may be capitalized or preceded by an "l" to indicate that the corresponding argument points to a "double" item instead of "float".

To read a "long char" value, use one of the "h" placeholders.

The function returns the number of successfully matched and assigned input items. This may be used to determine how many input items were found. EOF is returned when end-of-file is encountered. A zero is returned when no conversions have been performed; this may occur if an inappropriate character is discovered in input, causing the scanning function to terminate.

Examples:

#include <stdio.h>
int i;
char s[100];
scanf("%d%s",&i,s);

may be executed on the input line

666     cheers!

to assign 666 to "i" and the string "cheers!\0" to "s". On the input line

    0084   0084

the number 84 is assigned to "i" and the string "0084\0" is assigned to "s".

Notes:

The "scanf" function (and its relatives "fscanf" and "sscanf") tend to vary from machine to machine. For example, other implementations of C may have additional control specifiers recognized in the "scanf" format string. Users who are familiar with C on one system should check for differences in "scanf" when moving to a new system.

Previous versions of "scanf" were not affected by the +18bitShorts option. Now, however, if you link with +18bitShorts, the arguments corresponding to "short" placeholders like "%hd" should be pointers to 18-bit short quantities.