[Previous]
[Contents]
[Next]

scanf()

scan formatted input from a file

Synopsis:

#include <stdio.h>

int scanf( const char *format, ... );

Description:

The scanf() function scans input from the file designated by stdin under control of the argument format. The format string is described below. Following the format string is the list of addresses of items to receive values.

Format control string

The format control string consists of zero or more format directives that specify acceptable input file data. Subsequent arguments are pointers to various types of objects that are assigned values as the format string is processed.

A format directive can be a sequence of one or more white-space characters, an ordinary character, or a conversion specifier:

As each format directive in the format string is processed, the directive may successfully complete, fail because of a lack of input data, or fail because of a matching error as defined by the particular directive:

Trailing white-space characters, including newline characters, are not read unless matched by a directive. When a format directive fails, or the end of the format string is encountered, the scanning is completed, and the function returns.

When one or more white-space characters (space, horizontal tab \t, vertical tab \v, form feed \f, carriage return \r, new line or linefeed \n) occur in the format string, input data up to the first non-whitespace character is read, or until no more data remains. If no white-space characters are found in the input data, the scanning is complete, and the function returns.

An ordinary character in the format string is expected to match the same character in the input stream.

Conversion specifiers

A conversion specifier in the format string is processed as follows:

Pointer-type specifications

A pointer-type specification is used to indicate the type of pointer used to locate the next argument to be scanned:

F
pointer is a far pointer
N
pointer is a near pointer

The pointer type defaults to that used for data in the memory model for which the program has been compiled.

Type length specifiers

A type length specifier affects the conversion as follows:

Conversion type specifiers

The valid conversion type specifiers are:

c
Any sequence of characters in the input stream of the length specified by the field width, or a single character if no field width is specified, is matched. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence, without a terminating null character ('\0'). For a single character assignment, a pointer to a single object of type char is sufficient.
d
A decimal integer, consisting of an optional sign, followed by one or more decimal digits, is matched. The argument is assumed to point to an object of type int.
e, f, g
A floating-point number, consisting of an optional sign (+ or -), followed by one or more decimal digits, optionally containing a decimal-point character, followed by an optional exponent of the form e or E, an optional sign and one or more decimal digits, is matched. The exponent, if present, specifies the power of ten by which the decimal fraction is multiplied. The argument is assumed to point to an object of type float.
i
An optional sign, followed by an octal, decimal or hexadecimal constant is matched. An octal constant consists of 0 and zero or more octal digits. A decimal constant consists of a nonzero decimal digit and zero or more decimal digits. A hexadecimal constant consists of the characters 0x or 0X followed by one or more (upper- or lowercase) hexadecimal digits. The argument is assumed to point to an object of type int.
n
No input data is processed. Instead, the number of characters that have already been read is assigned to the object of type unsigned int that is pointed to by the argument. The number of items that have been scanned and assigned (the return value) is not affected by the n conversion type specifier.
o
An octal integer, consisting of an optional sign, followed by one or more (zero or nonzero) octal digits, is matched. The argument is assumed to point to an object of type int.
p
A hexadecimal integer, as described for x conversions below, is matched. The converted value is further converted to a value of type void* and then assigned to the object pointed to by the argument.
s
A sequence of non-whitespace characters is matched. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence and a terminating null character, which is added by the conversion operation.
u
An unsigned decimal integer, consisting of one or more decimal digits, is matched. The argument is assumed to point to an object of type unsigned int.
x
A hexadecimal integer, consisting of an optional sign, followed by an optional prefix 0x or 0X, followed by one or more (upper- or lowercase) hexadecimal digits, is matched. The argument is assumed to point to an object of type int.
[c1c2...]
The longest, nonempty sequence of characters, consisting of any of the characters c1, c2, ..., called the scanset, in any order, is matched. The first character, c1 cannot be the caret character ('^'). If c1 is ], that character is considered to be part of the scanset and a second ] is required to end the format directive. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence and a terminating null character, which is added by the conversion operation.
Note: A dash (-) in the scanset doesn't indicate a range of characters. For example, the string [0-9] matches the characters 0, -, and 9, not the characters 0 through 9.
[^c1c2...]
The longest, nonempty sequence of characters, consisting of any characters other than the characters between the ^ and ], is matched. As with the preceding conversion, if c1 is ], it is considered to be part of the scanset, and a second ] ends the format directive. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence and a terminating null character, which is added by the conversion operation.

For example, the specification %[^\n] will match an entire input line, up to but not including the newline character.

Note: A dash (-) in the scanset doesn't indicate a range of characters. For example, the string [^0-9] matches characters other than 0, -, and 9, not characters other than 0 through 9.

A conversion type specifier of % is treated as a single ordinary character that matches a single % character in the input data. A conversion type specifier other than those listed above causes scanning to terminate, and the function to return.

The line 

scanf( "%s%*f%3hx%d", name, &hexnum, &decnum )

with input 

some_string 34.555e-3 abc1234

will copy "some_string" into the array name, skip 34.555e-3, assign 0xabc to hexnum and 1234 to decnum. The return value will be 3.

The program 

#include <stdio.h>

void main()
  {
    char string1[80], string2[80];

    scanf( "%[abcdefghijklmnopqrstuvwxyz"
       "ABCDEFGHIJKLMNOPQRSTUVWZ ]%*2s%[^\n]",
       string1, string2 );
    printf( "%s\n%s\n", string1, string2 );
  }

with input 

They may look alike, but they don't perform alike.

will assign "They may look alike" to string1, skip the comma (the "%*2s" will match only the comma; the following blank terminates that field), and assign " but they don't perform alike." to string2.

Returns:

The scanf() function returns EOF when the scanning is terminated by reaching the end of the input stream. Otherwise, the number of input arguments for which values were successfully scanned and stored is returned.

Examples:

To scan a date in the form "Saturday April 18 1987": 

#include <stdio.h>

void main()
  {
    int day, year;
    char weekday[10], month[12];

    scanf( "%s %s %d %d", weekday, month, &day, &year );
  }

Classification:

ANSI, (except for the F and N modifiers)

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

cscanf(), fscanf(), sscanf(), vcscanf(), vfscanf(), vscanf(), vsscanf()

[Previous]
[Contents]
[Next]