fgetws

fgetws is a wide-character input function in the C standard library, used to read a line of wide characters from a file stream into a wide-character array. It is the wide-character counterpart of fgets and is declared in the header <stdio.h>. The function signature is wchar_t *fgetws(wchar_t *restrict ws, int n, FILE *restrict stream).

It reads up to n-1 wide characters from stream, stopping after encountering a newline, or when end-of-file or an error occurs. If a newline is read, it is stored in the buffer, and a terminating null wide character is appended. The buffer pointed to by ws must have space for at least n wide characters. If n is less than or equal to zero, or if stream or ws is a null pointer, the behavior is undefined; in normal use, the function returns NULL on error or when end-of-file is reached with no characters read.

On a successful read, fgetws returns ws. If end-of-file is encountered after some characters have been read, those characters are stored, the terminator is added, and ws is returned. If an input failure occurs before any characters are read, or if the input is incompatible, the function returns NULL. The function is affected by the locale and wide-character encoding, and the stream must be wide-oriented for defined behavior.

See also: fgetwc, fwscanf, and other wide-character input functions in stdio, which operate on wchar_t streams and respect locale settings.