getwc(S)

Syntax

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

wint_t getwc(FILE *stream);
wint_t getwchar(void);
wint_t fgetwc(FILE *stream);

Description

fgetwc(S) converts the next character read from the input stream, stream, to its corresponding wide-character code and returns it. The routine also advances the file position indicator for the stream.

An error will make the resulting value of the file position indicator meaningless.

The call to getwc(S) is equivalent to a call to fgetwc( ), except that getwc( ) may be implemented as a macro. getwchar(S) is defined as getwc(stdin).

The st_atime field of the file associated with stream is marked for update when fgetwc( ) or getwc( ) returns successfully the first time, if the input data was not pushed back to stream by a prior call to ungetc(S) or a call to ungetwc(S). All subsequent calls of fgetwc( ) or getwc( ) may also update the st_atime field if a read(S) operation on stream is needed to fill the stdio buffer.

Return values

WEOF is also returned for a read error. When a read error occurs, errno is set to indicate the error, and the error indicator for the stream is set.

Diagnostics

[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.

[EILSEQ]

Invalid or incomplete multibyte character.

[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.

Notes

WEOF is returned for both an error and an end-of-file condition. Use ferror(S) or feof(S) to distinguish between these two possibilities.

For getwchar( ), never store the return value from getwchar( ), of type wint_t, into a variable of type wchar_t and compare against the wint_t macro WEOF. The comparison may never succeed. A similarity may be drawn here with storing the integer returned by fgetc(S) into a char variable and comparing this char variable against EOF.

getwc( ) is equivalent to fgetwc( ), and is provided for compatibility reasons. However, its use is not recommended because it may be implemented as a macro and may not treat correctly its argument with side effects, as in getwc(*f++).

See also

Standards conformance