| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
#include <wchar.h>
wchar_t *fgetws(wchar_t * __restrict__wcs, int n, FILE * __restrict__stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>
wchar_t *fgetws_unlocked(wchar_t * __restrict__wcs,
int n, FILE * __restrict__stream);Reads at most one less than the number of the wide characters specified by n, from the stream pointed to by stream, into the array pointed to by wcs. No additional wide characters are read after a newline wide character (which is retained) or after the EOF. A NULL wide character is written immediately after the last wide character read into the array.
The fgetws() function advances the file position unless there is an error, when the file position is undefined.
The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.
Using non-wide-character functions with fgetws() results in undefined behavior. This happens because fgetws() processes a whole multibyte character and does not expect to be “within” such a character. In addition, fgetws() expects state information to be set already. Because functions like fgetc() and fputc() do not obey such rules, their results fail to meet the assumptions made by fgetws().
fgetws() has the same restriction as any read operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.
fgetws_unlocked() is functionally equivalent to fgetws() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.
If successful, fgetws() returns the new value of wcs.
If EOF is encountered and no wide characters have been read into the array, the contents of the array remain unchanged and fgetws() returns a NULL pointer.
If a read error or an encoding error occurs during the operation, the array contents are indeterminate and fgetws() returns a NULL pointer. An encoding error is one that occurs when a wide character is converted to a multibyte character. If it occurs, errno is set to EILSEQ and fgetws() returns NULL.
If n is less than or equal to 0, it indicates a domain error; errno is set to EDOM to indicate the cause of the failure.
When n equals 1, it indicates a valid result. It means that the string buffer has only room for the NULL terminator; nothing is physically read from the file. (Such an operation is still considered a read operation, so it cannot immediately follow a write operation unless there is an intervening flush or reposition operation first.)
If n is greater than 1, fgets() will only fail if an I/O error occurs or if EOF is reached, and no data is read from the file. To find out which error has occurred, use either the feof() or the ferror() function. If EOF 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 result in NULL being returned because EOF would be reached without any data being read.
The ferror() and feof() functions are used to distinguish between a read error and an EOF. Note that 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.
⁄* CELEBF20 *⁄
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
FILE *stream;
wchar_t wcs[100];
wchar_t *ptr;
if ((stream = fopen("myfile.dat", "r")) == NULL) {
printf("Unable to open file\n");
exit(1);
}
errno = 0;
ptr = fgetws(wcs, 100, stream);
if (ptr == NULL) {
if (errno == EILSEQ) {
printf("An invalid wide character was encountered.\n");
exit(1);
}
else if (feof(stream))
printf("end of file reached\n");
else
perror("read error");
}
printf("wcs=\"%ls\"\n", wcs);
fclose(stream);
}