fgetws(S-osr5)

fgetws -- get a wide character string from a stream

Syntax

cc . . . -lc

#include <stdio.h>
#include <wchar.h>

wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);

Description

fgetws(S-osr5) converts characters read from the input stream, stream, to their corresponding wide-character codes. It places these wide-character codes in the wchar_t array pointed to by ws. At most, n-1 characters are read and converted; a newline character or an end-of-file condition signals the end of the input, although the newline character is still converted and transferred to ws. The wide-character string, ws, is then null-terminated and returned. The file position indicator is also advanced appropriately.

The resulting value of the file position indicator is meaningless if an error occurs.

The st_atime field of the file associated with stream is marked for update by the first successful execution of fgetws( ) if the input data was not pushed back to stream by a prior call to ungetc(S-osr5) or a call to ungetwc(S-osr5). All subsequent calls of fgetws( ) may also update the st_atime field if a read(S-osr5) operation on stream is needed to fill the stdio buffer.

Return values

fgetws( ) returns the converted string ws. If the stream is at end-of-file when fgetws( ) is called, the end of file indicator for the stream is set and fgetws( ) returns a null pointer. If a read error occurs, fgetws( ) returns a null pointer and sets errno to indicate the error. fgetws also sets the error indicator for the stream in this case.

Diagnostics

fgetws( ) will fail if data needs to be read and:

[EAGAIN]: Cannot read the input stream immediately without blocking the process, and the O_NONBLOCK flag is set for the file descriptor associated with stream.
[EBADF]: Not a valid file descriptor open for reading.
[EINTR]: The read operation was terminated by a signal before any data was read.
[EIO]: Cannot read from the controlling terminal. This happens when the process is in a background process group and the attempt by the process to read from its controlling terminal fails, either because the process group is orphaned, or because the process is ignoring or blocking the SIGTTIN signal.
[ENOMEM]: Not enough storage space available.
[ENXIO]: Attempt to read from a non-existent device, or from a device whose capabilities are exceeded.

Standards conformance