getwc, fgetwc, or getwchar Subroutine

Purpose

Gets a wide character from an input stream.

Library

Standard I/O Package (libc.a)

Syntax

#include <stdio.h>

wint_t getwc ( Stream)
FILE *Stream;

wint_t fgetwc (Stream)
FILE *Stream;
wint_t getwchar (void)

Description

The fgetwc subroutine obtains the next wide character from the input stream specified by the Stream parameter, converts it to the corresponding wide character code, and advances the file position indicator the number of bytes corresponding to the obtained multibyte character. The getwc subroutine is equivalent to the fgetwc subroutine, except that when implemented as a macro, it may evaluate the Stream parameter more than once. The getwchar subroutine is equivalent to the getwc subroutine with stdin (the standard input stream).

The first successful run of the fgetc (getc, getchar, fgetc, or getw Subroutine), fgets (gets or fgets Subroutine), fgetwc, fgetws (getws or fgetws Subroutine), fread (fread or fwrite Subroutine), fscanf, getc (getc, getchar, fgetc, or getw Subroutine), getchar (getc, getchar, fgetc, or getw Subroutine), gets (gets or fgets Subroutine), or scanf subroutine using a stream that returns data not supplied by a prior call to the ungetc or ungetwc subroutine marks the st_atime field for update.

Parameters

Item Description
Stream Specifies input data.

Return Values

Upon successful completion, the getwc and fgetwc subroutines return the next wide character from the input stream pointed to by the Stream parameter. The getwchar subroutine returns the next wide character from the input stream pointed to by stdin.

If the end of the file is reached, an indicator is set and WEOF is returned. If a read error occurs, an error indicator is set, WEOF is returned, and the errno global variable is set to indicate the error.

Error Codes

If the getwc, fgetwc, or getwchar subroutine is unsuccessful because the stream is not buffered or data needs to be read into the buffer, it returns one of the following error codes:

Item Description
EAGAIN Indicates that the O_NONBLOCK flag is set for the file descriptor underlying the Stream parameter, delaying the process.
EBADF Indicates that the file descriptor underlying the Stream parameter is not valid and cannot be opened for reading.
EINTR Indicates that the process has received a signal that terminates the read operation.
EIO Indicates that a physical error has occurred, or the process is in a background process group attempting to read from the controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned.
EOVERFLOW Indicates that the file is a regular file and an attempt has been made to read at or beyond the offset maximum associated with the corresponding stream.

The getwc, fgetwc, or getwchar subroutine is also unsuccessful due to the following error conditions:

Item Description
ENOMEM Indicates that storage space is insufficient.
ENXIO Indicates that the process sent a request to a nonexistent device, or the device cannot handle the request.
EILSEQ Indicates that the wc wide-character code does not correspond to a valid character.