fgetws() — Read Wide-Character String from Stream
Format
#include <wchar.h>
#include <stdio.h>
wchar_t *fgetws(wchar_t *wcs, int n, 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 fgetws()
function
reads at most one less than the number of wide characters specified
by n from the stream pointed to by stream.
The fgetws()
function
stops reading characters after WEOF, or after it reads a new-line
wide character (which is retained). It adds a null wide character
immediately after the last wide character read into the array. The fgetws()
function
advances the file position unless there is an error. If an error occurs,
the file position is undefined.
Using non-wide-character functions with the fgetws()
function
on the same stream results in undefined behavior. After calling the fgetws()
function,
flush the buffer or reposition the stream pointer before calling a
write function for the stream, unless WEOF has been reached. After
a write operation on the stream, flush the buffer or reposition the
stream pointer before calling the fgetws()
function.
Return Value
If successful, the fgetws()
function
returns a pointer to the wide-character string wcs. If WEOF
is encountered before any wide characters have been read into wcs,
the contents of wcs remain unchanged and the fgetws()
function
returns a null pointer. If WEOF is reached after data has already
been read into the string buffer, the fgetws()
function
returns a pointer to the string buffer to indicate success. A subsequent
call would return NULL because WEOF would be reached without any data
being read.
If a read error occurs, the contents of wcs are
indeterminate, and the fgetws()
function
returns NULL. If an encoding error occurs (in converting a wide character
to a multibyte character), the fgetws()
function
sets errno to EILSEQ and returns NULL.
If n equals 1, the wcs buffer has only room
for the ending null character, and nothing is read from the stream.
(Such an operation is still considered a read operation, so it cannot
immediately follow a write operation unless the buffer is flushed
or the stream pointer repositioned first.) If n is greater
than 1, the fgetws()
function
fails only if an I/O error occurs, or if WEOF is reached before data
is read from the stream.
Use the ferror()
and feof()
functions
to distinguish between a read error and a WEOF. A WEOF error 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 WEOF indicator.
For information about errno values for fgetws()
, see fgetwc() — Read Wide Character from Stream.
Example
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
FILE *stream;
wchar_t wcs[100];
if (NULL == (stream = fopen("fgetws.dat", "r"))) {
printf("Unable to open: \"fgetws.dat\"\n");
exit(1);
}
errno = 0;
if (NULL == fgetws(wcs, 100, stream)) {
if (EILSEQ == errno) {
printf("An invalid wide character was encountered.\n");
exit(1);
}
else if (feof(stream))
printf("End of file reached.\n");
else
perror("Read error.\n");
}
printf("wcs = \"%ls\"\n", wcs);
fclose(stream);
return 0;
/************************************************************
Assuming the file fgetws.dat contains:
This test string should not return -1
The output should be similar to:
wcs = "This test string should not return -1"
************************************************************/
}