6.23.13 fwscanf Function

Scans formatted text from a stream, using a wide format string.

Attention: This function is implemented only by MPLAB XC32 C compilers.

Include

<wchar.h>

Prototype

int fwscanf(FILE * restrict stream, const wchar_t * restrict format, ...);

Arguments

stream
pointer to the open stream from which to read data
format
format control wide string
...
optional arguments; see “Remarks”

Return Value

Returns the number of items successfully converted and assigned. If no items are assigned, a 0 is returned. EOF is returned if end-of-file is encountered before the first conversion or if an error occurs.

Remarks

This function can read input from the specified stream.

The format string can be composed of white space wide characters, which reads input up to the first non-white-space wide character in the input; or ordinary wide characters, which if not read in that order, will trigger an error and leave the remaining characters in the input, unread. The format string can also contain conversion specifications, which begin with the % wide character and that specify the expected input sequences and how they are to be converted for assignment to objects pointed to by the pointer arguments.

Each conversion specification begins with a percent wide character followed by optional fields and a required type as shown here:

%[*][width][length]specifier

The presence of * immediately after the percent wide character indicates that the read and converted value should not be assigned to any object.

The width is a decimal integer that must be non-zero and indicates the maximum field width (in characters) of the input that is read to match the specification.

The length modifier specifies the size of the object in which the value will be assigned, as described in the following table. Their use with other conversion specifiers results in undefined behavior.

Modifier Meaning
h  When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a short int or unsigned short int object referenced by the pointer argument.
hh When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a signed char or unsigned char object referenced by the pointer argument.
l When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a long int or unsigned long int object referenced by the pointer argument.
l When used the a, A, e, E, f, F, g, or G indicates that this conversion specifier assigns to a double object referenced by the pointer argument.
l When used the c, s, or [ indicates that this conversion specifier assigns to a wchar_t object referenced by the pointer argument.
ll When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a long long int or unsigned long long int object referenced by the pointer argument.
L When used the a, A, e, E, f, F, g, G conversion specifier, indicates the argument value is a long double.
j When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a intmax_t or uintmax_t object referenced by the pointer argument.
t When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a ptrdiff_t object referenced by the pointer argument.
z When used with d, i, o, u, x, X, or n indicates that this conversion specifier assigns to a size_t object referenced by the pointer argument.

The conversion specifiers specify the type of conversion to be applied to the read sequence.

Specifier Receiving object type Matches
a double Matches an optionally signed floating-point number, infinity, or NaN, whose format is the same as expected by the strtod function for the first argument.
c char array, or wchar_t array

Matches a single wide character or the number of characters specified by the field width if present.

If no l length modifier is present, characters from the input field are converted to a multibyte character sequence (as if by calling wcrtomb). The corresponding argument shall be a pointer to the initial element of a character array of sufficient size. No null character is added.

If an l length modifier is present, the input shall be a wide character array of sufficient size. No null wide character is added.
d signed int Matches an optionally signed decimal integer, whose format is the same as expected by the strtod function for the first argument when using a value of 10 for the base argument.
e double Matches an optionally signed floating-point number, infinity, or NaN, whose format is the same as expected by the strtod function for the first argument.
f double Matches an optionally signed floating-point number, infinity, or NaN, whose format is the same as expected by the strtod function for the first argument.
g double Matches an optionally signed floating-point number, infinity, or NaN, whose format is the same as expected by the strtod function for the first argument.
i signed int Converted to signed decimal with the general form [−]dddd. The precision specifies the minimum number of digits to appear.
n int No input is consumed but the number of wide characters this call has so far read from the input stream is written to the argument with no increment of the assignment count returned by the function. If the conversion specification includes an assignment-suppressing character or a field width, the behavior is undefined.
o unsigned int Matches an optionally signed decimal integer, whose format is the same as expected by the strtoul function for the first argument when using a value of 8 for the base argument.
p void * * Matches an implementation-defined set of sequences, which should be the same as the set of sequences that may be produced by the %p conversion of the fwprintf function. The input item is converted to a pointer value in an implementation-defined manner. If the input item is a value converted earlier during the same program execution, the pointer that results shall compare equal to that value; otherwise the behavior of the %p conversion is undefined.
s char array, or wchar_t array

Matches a sequences of non-white-space wide characters, which is written to the array argument.

If no l length modifier is present, characters from the input field are converted to a multibyte character sequence (as if by calling wcrtomb). The corresponding argument shall be a pointer to the initial element of a character array large of sufficient size. A terminating null character is appended.

If an l length modifier is present, the corresponding argument shall be a pointer to the initial element of a wide character array of sufficient size. A terminating null wide character is appended.
x unsigned int Matches an optionally signed decimal integer, whose format is the same as expected by the strtoul function for the first argument when using a value of 8 for the base argument.
% Matches a single % wide character. No assignment takes place.
[ char array, or wchar_t array

Matches all the wide characters in the input that have been specified between the [ and trailing ] wide character, unless the wide character after the opening bracket is a circumflex, ^, in which case a match is only made with wide characters that do not appear in the brackets. If the conversion specifier begins with [] or [^], the right bracket wide character will match the input and the next following right bracket wide character is the matching right bracket that ends the specification.

If no l length modifier is present, characters from the input field are converted to amultibyte character sequence (as if by calling wcrtomb). The corresponding argument shall be a pointer to the initial element of a character array large enough to accept the sequence and a terminating null character, which will be added automatically.

If an l length modifier is present, the corresponding argument shall be a pointer to the initial element of a wide array of sufficient size.A terminating null wide character will be appended.

Example 

#include <wchar.h>
#include <stdio.h>

int main(void)
{
  FILE *myfile;
  wchar_t s[30];
  int x;
  wchar_t a;

  if ((myfile = fopen("afile", "w+")) == NULL)
    wprintf(L"Cannot open afile\n");
  else
  {
    fwprintf(myfile, L"%ls %d times%lc", L"Print this string", 100, L'.');

    fseek(myfile, 0L, SEEK_SET);

    fwscanf(myfile, L"%ls", s);
    wprintf(L"%ls\n", s);
    fwscanf(myfile, L"%ls", s);
    wprintf(L"%ls\n", s);
    fwscanf(myfile, L"%ls", s);
    wprintf(L"%ls\n", s);
    fwscanf(myfile, L"%d", &x);
    wprintf(L"%d\n", x);
    fwscanf(myfile, L"%ls", s);
    wprintf(L"%ls\n", s);

    fclose(myfile);
  }
}

Example Input

Contents of afile:

Print this string 100 times.

Example Output 

Print
this
string
100
times.