getwc, fgetwc, or getwchar Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

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>

win_t getwc (Stream)
FILE *Stream;

win_t fgetwc (Stream)
FILE *Stream;

win_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

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:

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:

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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

Other wide character I/O subroutines: getws or fgetws subroutine, putwc, putwchar, or fputwc subroutine, putws or fputws subroutine, ungetwc subroutine.

Related standard I/O subroutines: fopen, freopen, or fdopen subroutine, gets or fgets subroutine, fread subroutine, fwrite subroutine, printf, fprintf, sprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf subroutine, putc, putchar, fputc, or putw subroutine, puts or fputs subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character Input/Output Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.