scanf()

Scan formatted input from stdin

Synopsis:

#include <stdio.h>

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

Description:

The scanf() function scans input from stdin under control of the format argument, assigning values to the remaining arguments.

The format control string consists of zero or more format directives that specify acceptable input 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 whitespace characters or:

If the multibyte string is invalid, processing stops and the rest of the format string is output, including the % characters. The C-TRADITIONAL locale switches multibyte processing from UTF-8 to 1-to-1 and safely transfers misformed multibyte characters.

multibyte characters

Any character in the format string, other than a whitespace character or the percent character (%), that isn't part of a conversion specifier.

conversion specifiers

A sequence of characters in the format string that begins with a percent character (%) and is followed, in sequence, by:

an optional assignment suppression indicator: the asterisk character (*)
an optional decimal integer that specifies the maximum field width to be scanned for the conversion
an optional type length specification: one of h, L, or l
a character that specifies the type of conversion to be performed: one of the characters: c, d, e, f, g, i, n, o, p, s, u, X, x, [

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

If end-of-file is encountered on the input data before any characters that match the current directive have been processed (other than leading whitespace, where permitted), the directive fails for lack of data.

If end-of-file occurs after a matching character has been processed, the directive is completed (unless a matching error occurs), and the function returns without processing the next directive.

If a directive fails because of an input character mismatch, the character is left unread in the input stream.

Trailing whitespace characters, including newline characters, aren't 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 whitespace characters (space, horizontal tab \t, vertical tab \v, form feed \f, carriage return \r, newline 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 whitespace 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:

For conversion types other than [, c and n, leading whitespace characters are skipped.
For conversion types other than n, all input characters, up to any specified maximum field length, that can be matched by the conversion type are read and converted to the appropriate type of value; the character immediately following the last character to be matched is left unread; if no characters are matched, the format directive fails.
Unless the assignment suppression indicator (*) was specified, the result of the conversion is assigned to the object pointed to by the next unused argument (if assignment suppression was specified, no argument is skipped); the arguments must correspond in number, type and order to the conversion specifiers in the format string.

Type length specifiers

A type length specifier affects the conversion as follows:

hh causes a d, i, o, u, x, X or n format conversion to assign the converted value to an object of type signed char or unsigned char.
h causes a d, i, o, u, x, X or n (integer) format conversion to assign the converted value to an object of type short or unsigned short.
j causes a d, i, o, u, x, X or n conversion to assign the converted value to an object of type intmax_t or uintmax_t.
l (ell) causes a d, i, o, u, x, X or n (integer) conversion to assign the converted value to an object of type long or unsigned long.
l (ell) causes an a, A, e, E, f, F, g or G conversion to assign the converted value to an object of type double.
l (ell) causes a c, s or [ conversion to assign the converted value to an object of type wchar_t.
ll (ell-ell) causes a d, i, o, u, x, X or n format conversion to assign the converted value to an object of type long long or unsigned long long.
L causes an a, A, e, E, f, F, g or G conversion to assign the converted value to an object of type long double.
t causes a d, i, o, u, x, X or n conversion to assign the converted value to an object of type ptrdiff_t or to the corresponding unsigned type.
z causes a d, i, o, u, x, X or n conversion to assign the converted value to an object of type size_t or to the corresponding signed integer type.

Conversion type specifiers

The valid conversion type specifiers are:

a, A, e, E, f, F, g or G

A floating-point number, infinity or NaN all of which have a format as expected by strtod(). The argument is assumed to point to an object of type float.

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. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence, without a terminating NUL character ('\0'). For a single character assignment, a pointer to a single object of type char is sufficient.

When an l (ell) qualifier is present, a sequence of characters are inputted from the initial shift state to wchar_t wide characters as if by a call to mbrtowc(). The conversion state is described by a mbstate_t object.

d

A decimal integer with a format as expected by strtol() and a base of 10. The argument is assumed to point to an object of type int.

i

An optionally signed integer with a format as expected by strtol() and a base of 0. 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 int that's pointed to by the argument. The number of items that have been scanned and assigned (the return value) isn't affected by the n conversion type specifier.

o

An optionally signed octal integer with a format as expected by strtoul() and a base of 8.The argument is assumed to point to an object of type int.

p

A hexadecimal integer, as described for x conversions below. The converted value is taken as a void * and then assigned to the object pointed to by the argument.

s

A sequence of non-whitespace characters. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence of char, signed char or unsigned char and a terminating NUL character, which is added by the conversion operation.

u

An unsigned decimal integer, consisting of one or more decimal digits. The argument is assumed to point to an object of type unsigned int.

x, X

A hexadecimal integer, with a format which have a format as expected by strtoul() when base is 16. The argument is assumed to point to an object of type unsigned.

[

Matches the scanset, a nonempty sequence of characters. The argument is assumed to point to the first element of a character array of sufficient size to contain the sequence and a terminating NUL character, which is added by the conversion operation.

When an l (ell) qualifier is present, a sequence of characters are inputted from the initial shift state to wchar_t wide characters as if by a call to mbrtowc() with mbstate set to 0. The argument is assumed to point to the first element of a wchar_t array of sufficient size to contain the sequence and a terminating NUL character, which is added by the conversion operation.

The conversion specification includes all characters in the scanlist between the beginning [ and the terminating ]. If the conversion specification starts with [^, the scanlist will contain all the characters that aren't in the scanlist. If the conversion specification starts with [] or [^], the ] is included in the scanlist. (Scanning for ] only would be specified as %[]].)

%

A % character (The entire specification is %%).

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 returns with an error.

Returns:

EOF: Failure; the scanning stopped by reaching the end of the input stream before storing any values.
x: Success; the number of input arguments for which values were successfully scanned and stored.

Examples:

The line:

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

with input:

some_string 34.555e-3 abc1234

copies "some_string" into the array name, skips 34.555e-3, assigns 0xabc to hexnum and 1234 to decnum. The return value is 3.

The program:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

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

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

    printf( "%s\n", string1 );
    printf( "%s\n", string2 );
    
    return EXIT_SUCCESS;
}

with input:

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

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

To scan a date in the form "Friday March 26 1999":

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

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

    retval = scanf( "%s %s %d %d",
                    weekday, month, &day, &year );
    if( retval != 4 ) {
        printf( "Error reading date.\n" );
        printf( "Format is: Friday March 26 1999\n" );
        
        return EXIT_FAILURE;
    }
    
    printf( "weekday: %s\n", weekday );
    printf( "month: %s\n", month );
    printf( "day: %d\n", day );
    printf( "year: %d\n", year );
    
    return EXIT_SUCCESS;
}

Classification:

ANSI

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes