fwscanf() — Read Data from Stream Using Wide Character

Format

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

Language Level: ANSI

Threadsafe: Yes.

Locale Sensitive: The behavior of this function might be affected by the LC_CTYPE and LC_NUMERIC categories of the current locale. It might also be affected by the LC_UNI_CTYPE and LC_UNI_NUMERIC categories of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Integrated File System Interface: This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Wide Character Function: See Wide Characters for more information.

Description

The fwscanf() function 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, the fwscanf() function uses subsequent arguments as pointers to the objects.

Each argument in 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, the fwscanf() function evaluates the excess arguments, but otherwise ignores them.

The format consists of 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 the scanf()function, 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 the wcrtomb() function. The array includes the ending null character.
%ls and %S copy an array of wchar_t, including the ending null wide character, to an array of wchar_t.

If the data is from stdin, and stdin has not been overridden, the data is assumed to be in the CCSID of the job. The data is converted as required by the format specifications. If the file that is being read is not opened with file mode rb, then invalid conversion can occur.

If a conversion specification is invalid, the behavior is undefined. If the fwscanf() function encounters end-of-file during input, conversion is ended. If end-of-file occurs before the fwscanf() function reads any characters matching the current directive (other than leading white space, where permitted), execution of the current directive ends 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) ends with an input failure.

The fwscanf() function 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

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

If an input failure occurs before any conversion, the fwscanf() function returns EOF.

Example that uses fwscanf()

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
   ***********************************************/
}

Unicode example that uses fwscanf()

This example reads a Unicode string from unicode.dat and prints it to the screen. The example is compiled with LOCALETYPE(*LOCALEUCS2) SYSIFCOPT(*IFSIO):

#include   <stdio.h>
#include   <wchar.h>
#include   <locale.h>
void main(void)
{
FILE *stream;
wchar_t buffer[20];
stream=fopen("unicode.dat","rb");

fwscanf(stream,L"%ls", buffer);
wprintf(L"The string read was :%ls\n",buffer);

fclose(stream);
}

/* If the input in unicode.dat is :
 ABC
 and ABC is in unicode which in hex would be 0x0041, 0x0042, 0x0043
 then the output will be similar to:
 The string read was :ABC
*/

Related Information

[ Top of Page | Previous Page | Next Page | Contents | Index ]