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>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, fgets, fgetwc, fgetws, fread, fscanf, getc, getchar, gets, 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. |