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 %.
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
#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
#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
*/