Descripton | Description These functions are used for formatted input. They read the input, convert it according to the specifications in the format string format and store the result in the area that was specified in the optional argument list arglist. fwscanf() reads formatted input from the file pointed to by dz.
swscanf() reads formatted input from the wide character string s. swscanf() is the same as the fwscanf() function otherwise. The end of the wide character string is EOF.
wscanf() reads formatted input from the standard input stdin. wscanf() is the same as the fwscanf() function with dz = stdin.
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 char (but no white-space characters 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 the input characters without converting them at first and stores them 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 because a wide character does not fit, then this character is left unread in the input stream. 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; they 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 character *. 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 bytes) or matching failures (due to inappropriate input).
A directive composed of one or more white-space characters is executed by reading input until no more valid wide characters can be read (EOF), or up to the first byte which is not a white-space character (which remains unread). A directive that is an ordinary 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 wide characters 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 bytes (up to any specified maximum field width) which is an initial subsequence of a matching sequence. The first byte, if any, after the input item 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 error prevented input, in which case it is an input failure. Except in the case of a % conversion character, the input item (or, in the case of a %n conversion specification, the count of input bytes) is converted to a 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 have the following format: %[ m | *] { [hh|h|l|ll|j|z|t]{d|i|o|n|u|x|X} |
[l] {c|s} |
[l|L] {a|A|e|E|f|F|g|G} |
{p} |
[l] {[...]|[^...]} |
% }
d
| Matches an optionally signed decimal integer, whose format is the same as expected for wcstol() with the value 10 for base. 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 wcstol() with the value 0 for base. 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. 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 wcstoul() with the value 10 for base. 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 wcstoul() with the value 16 for base. 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
| Reads a sequence of wide characters that are not white space characters.
If l is not specified, the sequence is converted to a sequence of wide character codes in the same manner as wcrtomb(). The conversion status is written to an object of type mbstate_t and initialized to 0 before the first wide character is converted. Data is written up to the terminating null character. The corresponding argument must be a pointer to the first byte of an array of type char, which must be large enough to accept the sequence and a terminating null byte, which will be added automatically.
If l is specified, the corresponding argument must be a pointer to the initial byte of a wchar_t array that is large enough to accept the sequence and a terminating null character byte, which will be added automatically. | [
| Matches a non-empty sequence of bytes from a set of expected bytes (the scanset).
If l is not specified, the sequence is converted to a sequence of wide character codes in the same manner as wcrtomb(). The conversion status is written to an object of type mbstate_t and initialized to 0 before the first wide character is converted. Data is written up to the terminating null character. The corresponding argument must be a pointer to the first byte of an array of type char, which must be large enough to accept the sequence and a terminating null byte, which will be added automatically. If l is specified, the corresponding argument must be a pointer to the initial byte of a wchar_t array that is large enough to accept the sequence and a terminating null character byte, which will be added automatically. The conversion specification includes all subsequent wide characters 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 first wide characters 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 last character nor the first character after [ or [^ , 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 an int into which the number of input wide characters read thus far by this call are to be entered. Execution of a % n conversion specification does not increment the assignment count returned at the completion of 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 failure. Otherwise, unless execution of the current conversion specification is terminated with a matching failure, execution of the following conversion specification (if different from % n) is terminated with an input failure. Reaching the end of the string in a swscanf() call is equivalent to encountering the endof-file indicator during an fwscanf() call. Any trailing white space (including newline 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. |
