### fwscanf -- Read Data from Stream Using Wide-Character Format String

Format

>     #include <stdio.h>
>     #include <wchar.h>
>     int fwscanf(FILE *stream, const wchar_t *format, argument-list);

Language Level: ANSI 93
fwscanf reads input from the stream pointed to by stream, under control of the wide string pointed to by format. The format string specifies the admissible input sequences and how they are to be converted for assignment. To receive the converted input, fwscanf uses subsequent arguments as pointers to the objects.

Each argument in the argument-list must point to a variable with a type that corresponds to a type specifier in format.

If insufficient arguments exist for the format, the behavior is undefined. If the format is exhausted while arguments remain, fwscanf evaluates, as usual, the excess arguments, but otherwise ignores them.

The format comprises zero or more directives: one or more white-space wide characters; an ordinary wide character (neither % nor a white-space wide character); or a conversion specification. Each conversion specification is introduced by a %.

The format has the same form and function as the format string for scanf, with the following exceptions:

- %c (with no l prefix) converts one or more wchar_t characters (depending on precision) to multibyte characters, as if by calling wcrtomb.
- %lc and %C convert one or more wchar_t characters (depending on precision) to an array of wchar_t.
- %s (with no l prefix) converts a sequence of non-white-space wchar_t characters to multibyte characters, as if by calling wcrtomb. The array includes the terminating null character.
- %ls and %S copy an array of wchar_t, including the terminating null wide character, to an array of wchar_t.

For a complete description of format specifiers, see scanf -- Read Data.

If a conversion specification is invalid, the behavior is undefined.

If fwscanf encounters end-of-file during input, conversion is terminated. If end-of-file occurs before fwscanf reads any characters matching the current directive (other than leading whitespace, where permitted), execution of the current directive terminates with an input failure. Otherwise, unless execution of the current directive terminates with a matching failure, execution of the following directive (other than %n, if any) terminates with an input failure.

fwscanf leaves trailing white space (including new-line wide characters) unread, unless matched by a directive. You cannot determine the success of literal matches and suppressed assignments other than through the %n directive.

Return Value
If an input failure occurs before any conversion, fwscanf returns the value of the macro EOF.

Otherwise, fwscanf returns the number of input items assigned, which can be fewer than provided for, in the event of an early matching failure.

Example
This example opens the file myfile.dat for input and then scans this file for a string, a long integer value, a character, and a floating-point value.

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

    #define  MAX_LEN       80

    int main(void)
    {
       FILE *stream;
       long l;
       float fp;
       char s[MAX_LEN+1];
       char c;

       stream = fopen("myfile.dat", "r");

        /* Read data from file. */

       fwscanf(stream, L"%s", &s[0]);
       fwscanf(stream, L"%ld", &l);
       fwscanf(stream, L"%c", &c);
       fwscanf(stream, L"%f", &fp);

       printf("string = %s\n", s);
       printf("long integer = %ld\n", l);
       printf("char = %c\n", c);
       printf("float = %f\n", fp);
       return 0;

       /***********************************************
          If myfile.dat contains:
          abcdefghijklmnopqrstuvwxyz 343.2.

          The output should be:

          string = abcdefghijklmnopqrstuvwxyz
          long integer = 343
          char = .
          float = 2.000000
       ***********************************************/
    }

fscanf -- Read Data from a Stream
scanf -- Read Data
fwprintf -- Format Data as Wide Characters and Write to a Stream
swprintf -- Format and Write Wide Characters to Buffer
swscanf -- Read Wide-Character Data from Buffer
wscanf -- Read Data Using Wide-Character Format String
<stdio.h>
<wchar.h>