| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
#include <wchar.h>
wint_t fgetwc(FILE *stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>
wint_t fgetwc_unlocked(FILE *stream);Obtains 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).
The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.
Using non-wide-character functions with fgetwc() results in undefined behavior. This happens because fgetwc() processes a whole multibyte character and does not expect to be “within” such a character. In addition, fgetwc() expects state information to be set already. Because functions like fgetc() and fputc() do not obey such rules, their results fail to meet the assumptions made by fgetwc().
fgetwc() has the same restriction as any read operation for read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.
fgetwc_unlocked() is functionally equivalent to fgetwc() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.
If successful, fgetwc() 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 fgetwc() returns WEOF. If an encoding error occurs (an error converting the multibyte character into a wide character), the value of the macro EILSEQ (illegal sequence) is stored in errno and WEOF is returned.
The ferror() and feof() functions are used to distinguish between a read error and an EOF. Note that 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.
⁄* CELEBF19 *⁄
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <errno.h>
int main(void)
{
FILE *stream;
wint_t wc;
if ((stream = fopen("myfile.dat", "r")) == NULL) {
printf("Unable to open file\n");
exit(1);
}
errno = 0;
while ((wc = fgetwc(stream)) != WEOF)
printf("wc=0x%X\n", wc);
if (errno == EILSEQ) {
printf("An invalid wide character was encountered.\n");
exit(1);
}
fclose(stream);
}