Reading Formatted Input

Describes conversion specifiers used for reading text. Functions that read formatted input, fscanf() and its related functions, accept an argument that specifies the format of the input text that the function should expect. This argument is a pointer to a character string containing normal text, whitespace (space, tab, newline characters), and conversion specifications. The normal text specifies literal characters that must be matched in the input stream. A whitespace character tells the function to skip whitespace characters until a non-whitespace character is encountered. A conversion specification tells the function which characters in the input stream should be converted to binary values and stored.

The conversion specifications must have matching arguments in the order they appear in the formatting argument. The arguments matching the conversion specification arguments must be pointers to objects of the relevant types.

A conversion specification describes the format of a character representation and how it should be converted to a binary value. A conversion specification contains these characters, in order from left to right:

a percent sign (%)
optional maximum field width specification or assignment suppression
optional argument size or type specification
the type of conversion to perform

A conversion specification's characters must not be separated by white space. Doubling the percent sign (%%) results in the output of a single %.

After the initial percent sign (%), a conversion specification contains an optional maximum width, specified in decimal digits. This width specifies the maximum number of characters to read for the conversion.

Instead of specifying width, use the optional assignment suppression character (*) to read an item without assigning it to an argument. A conversion specification with an assignment suppression must not have a corresponding argument.

The next part of a conversion specification is optional. It specifies additional type or size information about the argument in which the conversion's result will be stored. The following table lists these optional items.

The last character of a conversion specification denotes the type of conversion to perform and the type of the argument in which the value of the conversion will be stored.

The conversion specifier %[ begins a scanset. A scanset specifies which characters to accept. A scanset ends with a ] character. The characters read from input that match a scanset are stored in the character string pointed to by the scanset's corresponding argument.

Input stream characters are read until a character is found that is not in the scanset. If the first character of scanset is a circumflex (^) then input stream characters are read until a character from the scanset is read. A nul character is appended to the end of the stored character array.

For example, the conversion specifier %[abcdef] specifies that the scanset is abcdef and any of the characters "a" through "f" are to be accepted and stored. When a character outside this set is encountered, the function will stop reading and storing the scanset conversion and continue with the rest of the conversion specifiers.

For example, assuming the declaration:

  char str[20];

the execution of

  sscanf("acdfxbe", "%[abcdef]", str);

will store acdf in str. The text "xbe" will not be stored because the "x" is not in the scanset.

If the first character of the scanset is the circumflex, ^, then the following characters define an exclusionary scanset. This kind of scanset specifies that any character outside a scanset will be accepted.

For example, the statement

  sscanf("stuvawxyz", "%[^abcdef]", str);

will store "stuv" in str. If you want ^ to be part of the scanset, you cannot list it as the first character because it will be interpreted as introducing the members of an exclusionary scanset. For example, %[^abc] defines the exclusionary scanset "abc" but %[a^bc] defines the scanset "abc^" . %[^a^bc] and %[^^abc] both define a scanset equivalent to "abc^" .

If you want "]" to be in the scanset, it must be the first character of the scanset, immediately following the %[ or, to be in an exclusionary scanset, immediately after the ^. For example, %[]abc] specifies the scanset "]abc" and %[^]abc] defines the exclusionary scanset "^]abc" . In any other position, the ] will be interpreted as terminating the scanset. For example, %[ab]cd] specifies a scanset "ab" followed by the character c and d.

EWL adds an extension to the scanset interpretation rules specified in the ISO/IEC standards. EWL interprets such a use of - in a scanlist as defining a range of characters. For example, the conversion specification

  %[a-z]

is the same as the

  %[abcdefghijklmnopqrstuvwxyz]

To include the - character in the scanset, it must be either listed first (possibly after an initial ^) or last. Examples: %[-abc], %[abc-], %[^-abc], or %[^abc-]. Note also that it is assumed that the numeric value of the character before the - is less than that of the one after. If this relationship does not hold the result is undefined.

Table 1. Specifying Additional Size or Type Information About an Argument
Character	Description
`h`	The following d, i, o, u, x, X or n conversion will be stored in an object of type `short int` or `unsigned short int`.
`hh`	The following d, i, o, u, x, X or n conversion will be stored in an object of type `char` or `unsigned char`.
`l`	When used with integer conversion specifier, the l flag indicates that the argument points to an object of type `long int` or `unsigned long int`. When used with floating point conversion specifier, the l flag that the argument points to an object of type `double`. When used with a c or s conversion specifier, the l flag indicates that the corresponding argument is a pointer to an object of type `wchar_t`.
`ll`	The following integer conversion specifier has an argument that points to an object of type `long long` or `unsigned long long`.
`L`	The following floating-point conversion specifier has an argument that points to an object of type `long double`.
`v`	The argument points to an object containing an AltiVec vector of type `bool char`, `signed char`, or `unsigned char` when followed by c, d, i, o, u, x, or X. A vector of type `float`, when followed by f.
`vh or hv`	The argument points to an object containing an AltiVec vector of type `short`, `short bool`, `bool short`, or `pixel` when followed by c, d, i, o, u, x, or X.
`vl or lv`	The argument points to an object containing an AltiVec vector of type `int`, `unsigned in`, or `bool int` when followed by c, d, i, o, u, x, or X.

The table below specifies the types of conversion.

Table 2. Specifying the Type of Conversion
Character	Conversion
c	A character. Whitespace characters are not skipped.
d	A signed decimal number.
i	A signed decimal, octal, or hexadecimal number. The character representation can be prefixed by a plus (+) or minus (-) sign. Octal numbers begin with the zero (0) character. Hexadecimal numbers begin with 0x or 0X.
e, E, f, F, g, or G	A floating point number in scientific notation.
n	Stores the number of characters read by the function so far. Its corresponding argument must be a pointer to an `int`.
`o`	An unsigned octal.
`p`	A memory address. The input text must be the same as the format used by the `p` output format.
`s`	A character string. The function terminates the string with a nul-character when it encounters a whitespace character or the maximum number of characters has been read.
`#s`	A character string. The corresponding argument is a pointer to Pascal character string. A Pascal string is a length byte followed by the number of characters specified by the length byte. This conversion type is an extension to the ISO/IEC standards.
`u`	An unsigned decimal.
`x` or `X`	An unsigned hexadecimal.
[ `scanset`]	A scanset specification.