ILE C/C++ Run-Time Library Functions


fgetwc() -- Read Wide Character from Stream

Format

#include <wchar.h>
#include <stdio.h>
wint_t fgetwc(FILE *stream);

Language Level: ANSI

Threadsafe: Yes.

Description

The fgetwc() reads the next multibyte character from the input stream pointed to by stream, converts it to a wide character, and advances the associated file position indicator for the stream (if defined).

Using non-wide-character functions with fgetwc() on the same stream results in undefined behavior. After calling fgetwc(), flush the buffer or reposition the stream pointer before calling a write function for the stream, unless EOF has been reached. After a write operation on the stream, flush the buffer or reposition the stream pointer before calling fgetwc().

Notes:

  1. The behavior of the fgetwc() function is affected by the LC_CTYPE category of the current locale. If you change the category between subsequent read operations on the same stream, undefined results can occur.

  2. This function is not available when either LOCALETYPE(*CLD) or SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Return Value

The fgetwc() function returns the next wide character that corresponds to the multibyte character from the input stream pointed to by stream. If the stream is at EOF, the EOF indicator for the stream is set, and fgetwc() returns WEOF.

If a read error occurs, the error indicator for the stream is set, and the fgetwc() function returns WEOF. If an encoding error occurs (an error converting the multibyte character into a wide character), the fgetwc() function sets errno to EILSEQ and returns WEOF.

Use the ferror() and feof() functions to distinguish between a read error and an EOF. EOF is only reached when an attempt is made to read past the last byte of data. Reading up to and including the last byte of data does not turn on the EOF indicator.

The value of errno may be set to:

Value
Meaning

EBADF
The file pointer or descriptor is not valid.

ENOTREAD
The file is not open for read operations.

EGETANDPUT
An read operation that was not allowed occurred after a write operation.

ERECIO
The file is open for record I/O.

ESTDIN
stdin cannot be opened.

EIOERROR
A non-recoverable I/O error occurred.

EIORECERR
A recoverable I/O error occurred.

EILSEQ
An invalid multibyte character sequence was encountered.

ECONVERT
A conversion error occurred.

Example that uses fgetwc()

This example opens a file, reads in each wide character, and prints out the characters.


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 
#include <errno.h> 
 
int main(void) 
{ 
   FILE   *stream; 
   wint_t wc; 
 
   if (NULL == (stream = fopen("fgetwc.dat", "r"))) { 
      printf("Unable to open: \"fgetwc.dat\"\n"); 
      exit(1); 
   } 
 
   errno = 0; 
   while (WEOF != (wc = fgetwc(stream))) 
      printf("wc = %lc\n", wc); 
 
   if (EILSEQ == errno) { 
      printf("An invalid wide character was encountered.\n"); 
      exit(1); 
   } 
   fclose(stream); 
   return 0; 
} 
* * * End of File * * * 

Related Information


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