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 that uses fgetws()
This example opens a file, reads in the file contents, 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"
************************************************************/
}Related Information