fgetwc() — Read Wide Character from Stream
Format
#include <wchar.h>
#include <stdio.h>
wint_t fgetwc(FILE *stream);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE category of the current locale. The behavior might also be affected by the LC_UNI_CTYPE category 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 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()
.
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.
- 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
#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;
}