format is a character string, beginning and ending in its initial shift state, if defined. It is composed of zero or more directives and may include the following three types of characters:
- characters of type
wchar_t (but no white-space character or %), which are simply copied to the output stream (1: 1). - white-space characters, starting with a backslash (\) (see
iswspace).
conversion specifications beginning with the percent character (%), each of which is associated with zero or more arguments in arglist. The results are undefined if fewer arguments are passed in arglist than are defined in format. If the number of arguments defined in format is greater than the arguments passed in arglist, the excess arguments are ignored.
The wscanf functions read each input character, but do not initially convert it or store it in a variable. If the input character does not match the character specified in format, input processing is aborted, and the function returns. If the conversion is aborted due to an invalid wide character, the character involved remains in the input stream unread.
The control string format may include zero or more characters producing white space. These characters have no control function.
White-space characters in the input are treated as delimiters between input fields and are not converted (see %c, %n and %[] for exceptions). Leading white space in the input is ignored.
All forms of fwscanf allow for the insertion of a language-dependent radix character in the input string. The radix character is defined in the program ́s locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the radix character defaults to a period (.).
Each conversion specification is introduced by the % character, after which the following appear in sequence:
An optional assignment-suppressing wide character asterisk (*).
An optional non-zero decimal integer that specifies the maximum field width.
An optional size modifier hh, h, l, ll, L, j, z or t indicating the size of the receiving object:
l before the conversion characters c, s and [ : The corresponding argument is a pointer to wchar_t .
hh or h or l before d, i and n: The corresponding argument is a pointer to signed char (hh) or short int (h) or long int (l).
hh or h or l before o, u, x and X: The corresponding argument is a pointer to unsigned char (hh) or unsigned short int (h) or unsigned long int (l).
ll before d, i and n: The corresponding argument is a pointer to long long int.
ll before o, u, x and X: The corresponding argument is a pointer to unsigned long long int.
l or L before a, A, e, E, f, F, g and G : The corresponding argument is a pointer to double (l) or long double (L).
j before o, u, x and X: The corresponding argument is a pointer to uintmax_t.
j before d, i and n: The corresponding argument is a pointer to intmax_t.
z before o, u, x and X: The corresponding argument is a pointer to size_t.
z before d, i and n: The corresponding argument is a pointer to long int.
t before o, u, x and X: The corresponding argument is a pointer to unsigned long int.
t before d, i and n: The corresponding argument is a pointer to ptrdiff_t.
If hh, h, l, ll, L, j, z or t is specified before any other conversion character, the behavior is undefined.
A conversion character that specifies the type of conversion to be applied.
fwscanf executes each directive of the format in turn. If a directive fails, as detailed below, the function returns. Failures are described as input failures (due to the unavailability of input characters) or matching failures (due to inappropriate input).
A directive composed of one or more white-space characters is executed by reading input up to the first wide character which is not a white-space character (which remains unread), or until no more wide characters can be read (EOF).
A directive that is an ordinary wide character is executed as follows: the next wide character is read from the input and compared with the wide character that comprises the directive; if the comparison shows that they are not equivalent, the directive fails, and the differing and subsequent bytes remain unread.
A directive that is a conversion specification defines a set of matching input sequences, as described below for each conversion character. A conversion specification is executed in the following steps:
Input white-space characters are skipped, unless the conversion specification includes a [ or one of the conversion characters c or n.
An item is read from the input, unless the conversion specification includes an n conversion character. An input item is defined as the longest sequence of input characters (up to any specified maximum field width) that is an initial subsequence of a matching sequence. The first wide character after the input item, if any, remains unread.
If the length of the input item is 0, the execution of the conversion specification fails; this condition is a matching failure, unless an input error such as EOF, for example, or the occurrence of a read error prevents further input.
Except in the case of a % conversion character, the input item (or, in the case of a %n, the number of input characters read) is converted to a data type appropriate to the conversion character. If the input item is not a matching sequence, the execution of the conversion specification fails. This condition is a matching failure.
Unless assignment suppression was indicated by a *, the result of the conversion is placed in the object pointed to by the first argument following the format argument that has not already received a conversion result. If this object does not have an appropriate type, or if the result of the conversion cannot be represented in the space provided, the behavior is undefined.
Conversion specifications can be given as shown below:
% [*] [m] { [hh|h|l|ll|j|z|t]{d|i|o|n|u|x|X} |
[l]{c|s} |
[l|L]{e|E|f|g|G} |
p |
[l]{[...]|[^...]} |
%
}
|
d
| Matches an optionally signed decimal integer, whose format is the same as expected for the wcstol function with the value 10 for base (base = 10). The corresponding argument must be of type pointer to int. |
i
| Matches an optionally signed decimal integer, whose format is the same as expected for the wcstol function with the value 8 for base (base = 8). The corresponding argument must be of type pointer to int. |
o
| Matches an optionally signed octal integer, whose format is the same as expected for wcstoul with the value 8 for base (base = 8). The corresponding argument must be of type pointer to unsigned integer. |
u
| Matches an optionally signed decimal integer, whose format is the same as expected for the wcstoul function with the value 10 for base (base = 10). The corresponding argument must be of type pointer to unsigned integer. |
x, X
| Matches an optionally signed hexadecimal integer, whose format is the same as expected for the wcstoul function with the value 16 for base (base = 16). The corresponding argument must be of type pointer to unsigned integer. |
a, A, e, E, f, F, g, G |
| These conversion characters match an optionally signed floating-point number, whose format is the same as expected for wcstod(). The corresponding argument must be of type pointer to float. |
s
| Matches a sequence of non-white-space wide characters.
If no l (ell) qualifier is specified, characters from the input field are converted as if by repeated calls to the wcrtomb function, with the conversion state described by an mbstate_t object initialized to zero before the first wide character is converted. The sequence is written up to the terminating null character. The corresponding argument should be a pointer to a char array that is large enough to accept the converted sequence and a terminating null character, which will be added automatically.
If l is specified, the corresponding argument should be a pointer to the initial element of a wchar_t array that is large enough to accept the sequence and a terminating null wide character, which will be added automatically |
[
| Matches a non-empty sequence of wide characters from a set of expected wide characters (the scanset).
If no l (ell) qualifier is specified, characters from the input field are converted as if by repeated calls to the wcrtomb function, with the conversion state described by an mbstate_t object initialized to zero before the first wide character is converted. The sequence is written up to the terminating null character. The corresponding argument should be a pointer to a char array that is large enough to accept the converted sequence and a terminating null character, which will be added automatically. If l is specified, the corresponding argument should be a pointer to the initial element of a wchar_t array that is large enough to accept the sequence and a terminating null wide character, which will be added automatically.
The conversion specification includes all subsequent wide characters (i.e. characters after the [) in the format string up to and including the matching right square bracket (]). The wide characters between the square brackets (the scanlist) comprise the scanset, unless the wide character after the left square bracket is a circumflex (^), in which case the scanset contains all wide characters that do not appear in the scanlist between the circumflex ^ and the right square bracket ].
As a special case, if the conversion specification begins with [] or [^], the right square bracket is included in the scanlist, and the next right square bracket is the matching right square bracket that ends the conversion specification. If a - is in the scanlist and is not the first character, nor the second where the first character is a [ or [^, nor the last character, the behavior is undefined. |
c
| Matches a sequence of wide characters of the number specified by the field width. if no field width is specified in the conversion specification, 1 wide character is read.
If no l (ell) qualifier is specified, characters from the input field are converted as if by repeated calls to the wcrtomb function, with the conversion state described by an mbstate_t object initialized to zero before the first wide character is converted. The corresponding argument should be a pointer to a char array that is large enough to accept the converted sequence. No null character will be added.
If l is specified, the corresponding argument should be a pointer to the initial element of a wchar_t array that is large enough to accept the sequence. No null character will be added. The normal skip over white-space characters is suppressed in this case;
%1s should be used to read the next wide character that is not a white-space character. |
p
| Matches a set of sequences, which must be the same as the set of sequences that is produced by the %p conversion of the fwprintf functions. The corresponding argument must be a pointer to a pointer to void. The interpretation of the input item is implementation-dependent; if the input item is not a value that was converted earlier during the same program execution, the behavior of the %p conversion is undefined. This is specially true for pointer outputs generated by other systems. |
n
| No input is processed. The corresponding argument must be a pointer to int into which the number of wide characters read thus far by this call are to be entered. Execution of a %n conversion specification does not increment the assignment counter returned on completing the execution of the function. |
%
| Matches a single %; no conversion or assignment occurs. The complete conversion specification must be %%. |
If a conversion specification is invalid, the behavior of fwscanf is undefined.
If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any wide characters matching the current conversion specification have been read (other than leading white-space characters, where permitted), execution of the current conversion specification terminates with an input error. Otherwise, unless execution of the current conversion specification is terminated with a matching failure, an execution other than %n of the following conversion specification (if any) is terminated with an input error.
Reaching the end of the character string in a swscanf call is equivalent to encountering the end-of-file indicator during an fwscanf call.
Any trailing white space (including end-of-file characters) is left unread unless matched by a conversion specification.
The success of literal matches and suppressed assignments cannot be directly determined, except via the %n conversion specification.
