getwc() — Read Wide Character from Stream
Format
#include <stdio.h>
#include <wchar.h>
wint_t getwc(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. It 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 getwc()
function
reads the next multibyte character from stream, converts it to a wide
character, and advances the associated file position indicator for
stream.
The getwc()
function
is equivalent to the fgetwc()
function
except that, if it is implemented as a macro, it can evaluate stream
more than once. Therefore, the argument should never be an expression
with side effects.
If the current locale is changed between subsequent read
operations on the same stream, undefined results can occur. Using
non-wide-character functions with the getwc()
function
on the same stream results in undefined behavior.
After calling the getwc()
function,
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 the getwc()
function.
Return Value
The getwc()
function
returns the next wide character from the input stream, or WEOF. If
an error occurs, the getwc()
function
sets the error indicator. If the getwc()
function
encounters the end-of-file, it sets the EOF indicator. If an encoding
error occurs during conversion of the multibyte character, the getwc()
function
sets errno to EILSEQ.
Use the ferror()
or feof()
functions
to determine whether an error or an EOF condition occurred. 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.
For information about errno values for getwc()
, see fgetwc() — Read Wide Character from Stream.
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("getwc.dat", "r"))) {
printf("Unable to open: \"getwc.dat\"\n");
exit(1);
}
errno = 0;
while (WEOF != (wc = getwc(stream)))
printf("wc = %lc\n", wc);
if (EILSEQ == errno) {
printf("An invalid wide character was encountered.\n");
exit(1);
}
fclose(stream);
return 0;
/********************************************************
Assuming the file getwc.dat contains:
Hello world!
The output should be similar to:
wc = H
wc = e
wc = l
wc = l
wc = o
:
********************************************************/
}