scanf, fscanf, sscanf, or wsscanf Subroutine

Purpose

Converts formatted input.

Library

Standard C Library (libc.a)

or (libc128.a)

Syntax

#include <stdio.h>

Description

The scanf, fscanf, sscanf, and wsscanf subroutines read character data, interpret it according to a format, and store the converted results into specified memory locations. If the subroutine receives insufficient arguments for the format, the results are unreliable. If the format is exhausted while arguments remain, the subroutine evaluates the excess arguments but otherwise ignores them.

These subroutines read their input from the following sources:

The scanf, fscanf, sscanf, and wsscanf subroutines can detect a language-dependent radix character, defined in the program's locale (LC_NUMERIC), in the input string. In the C locale, or in a locale that does not define the radix character, the default radix character is a full stop . (period).

Parameters

The results from the conversion are placed in the memory location designated by the Pointer parameter unless you specify assignment suppression with an * (asterisk). Assignment suppression provides a way to describe an input field to be skipped. The input field is a string of nonwhite space characters. It extends to the next inappropriate character or until the field width, if specified, is exhausted.

The conversion code indicates how to interpret the input field. The corresponding Pointer parameter must be a restricted type. Do not specify the Pointer parameter for a suppressed field. You can use the following conversion codes:

%

Accepts a single % (percent sign) input at this point; no assignment or conversion is done. The complete conversion specification should be %% (two percent signs).

d

Accepts an optionally signed decimal integer with the same format as that expected for the subject sequence of the strtol subroutine with a value of 10 for the base parameter. If no size modifier is specified, the Pointer parameter should be a pointer to an integer.

i

Accepts an optionally signed integer with the same format as that expected for the subject sequence of the strtol subroutine with a value of 0 for the base parameter. If no size modifier is specified, the Pointer parameter should be a pointer to an integer.

u

Accepts an optionally signed decimal integer with the same format as that expected for the subject sequence of the strtoul subroutine with a value of 10 for the base parameter. If no size modifier is specified, the Pointer parameter should be a pointer to an unsigned integer.

o

Accepts an optionally signed octal integer with the same format as that expected for the subject sequence of the strtoul subroutine with a value of 8 for the base parameter. If no size modifier is specified, the Pointer parameter should be a pointer to an unsigned integer.

x

Accepts an optionally signed hexadecimal integer with the same format as that expected for the subject sequence of the strtoul subroutine with a value of 16 for the base parameter. If no size modifier is specified, the Pointer parameter should be a pointer to an integer.

e, f, or g

Accepts an optionally signed floating-point number with the same format as that expected for the subject sequence of the strtod subroutine. The next field is converted accordingly and stored through the corresponding parameter; if no size modifier is specified, this parameter should be a pointer to a float. The input format for floating-point numbers is a string of digits, with some optional characteristics:

• It can be a signed value.
• It can be an exponential value, containing a decimal rational number followed by an exponent field, which consists of an E or an e followed by an (optionally signed) integer.
• It can be one of the special values INF, NaNQ, or NaNS. This value is translated into the IEEE-754 value for infinity, quiet NaN, or signaling NaN, respectively.

p

Matches an unsigned hexadecimal integer, the same as the %p conversion of the printf subroutine. The corresponding parameter is a pointer to a void pointer. If the input item is a value converted earlier during the same program execution, the resulting pointer compares equal to that value; otherwise, the results of the %p conversion are unpredictable.

n

Consumes no input. The corresponding parameter is a pointer to an integer into which the scanf, fscanf, sscanf, or wsscanf subroutine writes the number of characters (including wide characters) read from the input stream. The assignment count returned at the completion of this function is not incremented.

s

Accepts a sequence of nonwhite space characters (scanf, fscanf, and sscanf subroutines). The wsscanf subroutine accepts a sequence of nonwhite-space wide-character codes; this sequence is converted to a sequence of characters in the same manner as the wcstombs subroutine. The Pointer parameter should be a pointer to the initial byte of a char, signed char, or unsigned char array large enough to hold the sequence and a terminating null-character code, which is automatically added.

S

Accepts a sequence of nonwhite space characters (scanf, fscanf, and sscanf subroutines). This sequence is converted to a sequence of wide-character codes in the same manner as the mbstowcs subroutine. The wsscanf subroutine accepts a sequence of nonwhite-space wide character codes. The Pointer parameter should be a pointer to the initial wide character code of an array large enough to accept the sequence and a terminating null wide character code, which is automatically added. If the field width is specified, it denotes the maximum number of characters to accept.

c

Accepts a sequence of bytes of the number specified by the field width (scanf, fscanf and sscanf subroutines); if no field width is specified, 1 is the default. The wsscanf subroutine accepts a sequence of wide-character codes of the number specified by the field width; if no field width is specified, 1 is the default. The sequence is converted to a sequence of characters in the same manner as the wcstombs subroutine. The Pointer parameter should be a pointer to the initial bytes of an array large enough to hold the sequence; no null byte is added. The normal skip over white space does not occur.

C

Accepts a sequence of characters of the number specified by the field width (scanf, fscanf, and sscanf subroutines); if no field width is specified, 1 is the default. The sequence is converted to a sequence of wide character codes in the same manner as the mbstowcs subroutine. The wsscanf subroutine accepts a sequence of wide-character codes of the number specified by the field width; if no field width is specified, 1 is the default. The Pointer parameter should be a pointer to the initial wide character code of an array large enough to hold the sequence; no null wide-character code is added.

[scanset]

Accepts a nonempty sequence of bytes from a set of expected bytes specified by the scanset variable (scanf, fscanf, and sscanf subroutines). The wsscanf subroutine accepts a nonempty sequence of wide-character codes from a set of expected wide-character codes specified by the scanset variable. The sequence is converted to a sequence of characters in the same manner as the wcstombs subroutine. The Pointer parameter should be a pointer to the initial character of a char, signed char, or unsigned char array large enough to hold the sequence and a terminating null byte, which is automatically added. In the scanf, fscanf, and sscanf subroutines, the conversion specification includes all subsequent bytes in the string specified by the Format parameter, up to and including the ] (right bracket). The bytes between the brackets comprise the scanset variable, unless the byte after the [ (left bracket) is a ^ (circumflex). In this case, the scanset variable contains all bytes that do not appear in the scanlist between the ^ (circumflex) and the ] (right bracket). In the wsscanf subroutine, the characters between the brackets are first converted to wide character codes in the same manner as the mbtowc subroutine. These wide character codes are then used as described above in place of the bytes in the scanlist. If the conversion specification begins with [] or [^], the right bracket is included in the scanlist and the next right bracket is the matching right bracket that ends the conversion specification. You can also:

• Represent a range of characters by the construct First-Last. Thus, you can express [0123456789] as [0-9]. The First parameter must be lexically less than or equal to the Last parameter or else the - (dash) stands for itself. The - also stands for itself whenever it is the first or the last character in the scanset variable.
• Include the ] (right bracket) as an element of the scanset variable if it is the first character of the scanset. In this case it is not interpreted as the bracket that closes the scanset variable. If the scanset variable is an exclusive scanset variable, the ] is preceded by the ^ (circumflex) to make the ] an element of the scanset. The corresponding Pointer parameter should point to a character array large enough to hold the data field and that ends with a null character (\0). The \0 is added automatically.

A scanf conversion ends at the end-of-file (EOF character), the end of the control string, or when an input character conflicts with the control string. If it ends with an input character conflict, the conflicting character is not read from the input stream.

Unless a match in the control string exists, trailing white space (including a new-line character) is not read.

The success of literal matches and suppressed assignments is not directly determinable.

The National Language Support (NLS) extensions to the scanf subroutines can handle a format string that enables the system to process elements of the argument list in variable order. The normal conversion character % is replaced by %n$, where n is a decimal number. Conversions are then applied to the specified argument (that is, the nth argument), rather than to the next unused argument.

The first successful run of the fgetc, fgets, fread, getc, getchar, gets, scanf, or fscanf subroutine using a stream that returns data not supplied by a prior call to the ungetc (ungetc or ungetwc Subroutine) subroutine marks the st_atime field for update.

Return Values

These subroutines return the number of successfully matched and assigned input items. This number can be 0 if an early conflict existed between an input character and the control string. If the input ends before the first conflict or conversion, only EOF is returned. If a read error occurs, the error indicator for the stream is set, EOF is returned, and the errno global variable is set to indicate the error.

Error Codes

The scanf, fscanf, sscanf, and wsscanf subroutines are unsuccessful if either the file specified by the Stream, String, or wcs parameter is unbuffered or data needs to be read into the file's buffer and one or more of the following conditions is true: