Format
#include <wchar.h> wchar_t *fgetws(wchar_t *wcs, int n, FILE *stream);
Language Level: ANSI 93, XPG4
fgetws reads wide characters from the stream
into the array pointed to by wcs. At most, n
- 1 wide characters are read. fgetws 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.
fgetws advances the file position unless there is an error. If an error occurs, the file position is undefined.
The behavior of fgetws 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.
Using non-wide-character functions with fgetws on the same stream results in undefined behavior.
After calling fgetws, 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 fgetws.
Return Value
If successful, fgetws 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 fgetws
returns a null pointer. If WEOF is reached after data has already
been read into the string buffer, fgetws 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 fgetws returns NULL. If an encoding error occurs (in converting a wide character to a multibyte character), fgetws sets errno to EILSEQ and returns NULL.
If n equals 1, the wcs buffer has only room for the terminating 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, fgetws fails only if an I/O error occurs or if WEOF is reached before data is read from the stream. Use ferror and feof to distinguish between a read error and a WEOF. WEOF 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.
Example
This example opens a file, reads in the
file contents using fgetws, then prints the file contents.
#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" ************************************************************/ }
![]()
fgets -- Read a String
fgetwc -- Read
Wide Character from Stream
fputws -- Write
Wide-Character String
<stdio.h>
<wchar.h>