NAME

getwc(), getwc_unlocked(), getwchar(), getwchar_unlocked(), fgetwc(), fgetwc_unlocked() − get a wide character from a stream file

SYNOPSIS

#include <wchar.h>

wint_t getwc(FILE *stream);

wint_t getwc_unlocked(FILE *stream);

wint_t getwchar(void);

wint_t getwchar_unlocked(void);

wint_t fgetwc(FILE *stream);

wint_t fgetwc_unlocked(FILE *stream);

Remarks:

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions.  They parallel the 8 bit character I/O functions defined in getc(3S).

DESCRIPTION

getwc() Returns the next character from the named input stream, converts that to the corresponding wide character and moves the file pointer ahead one character in stream. getwchar() is defined as getwc(stdin).  getwc() and getwchar() are defined both as macros and as functions. 

fgetwc() Behaves like getwc(), but is a function rather than a macro. 

Definitions for these functions, the types wint_t, wchar_t and the value WEOF are provided in header file <wchar.h>. 

getwc_unlocked(), getwchar_unlocked(), and fgetwc_unlocked() are identical to getwc(), getwchar(), and fgetwc(); respectively, except they do not perform any internal locking of the stream for multi-thread applications.  The _unlocked routines can be used by multi-thread applications which have already used flockfile() to acquire a mutual exclusion lock for the stream (see flockfile(3S)).

RETURN VALUE

Upon successful completion, getwc(), getwc_unlocked(), getwchar(), getwchar_unlocked(), fgetwc(), and fgetwc_unlocked() return the next wide character read from stream (stdin for getwchar()) converted to a type wint_t.  If the stream is at end-of-file, the end-of-file indicator for the stream is set and WEOF is returned.  If a read error occurs, the error indicator for the stream is set, errno is set to indicate the error, and WEOF is returned. 

ferror() and feof() can be used to distinguish between an error condition and an end-of-file condition. 

ERRORS

getwc(), getwc_unlocked(), getwchar(), getwchar_unlocked(), fgetwc(), and fgetwc_unlocked() fail if data needs to be read into the stream’s buffer, and:

[EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. 

[EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned. 

[EILSEQ] The data obtained from the input stream does not form a valid wide character. 

Additional errno values may be set by the underlying read() function (see read(2)).

EXTERNAL INFLUENCES

Locale

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support

Single- and multi-byte character code sets are supported. 

WARNINGS

If the value returned by getwc(), getwchar(), fgetwc(), or fgetwc_unlocked() is stored into a type wchar_t variable then compared against the constant WEOF, the comparison may never succeed because extension of a wchar_t to a wint_t is machine-dependent. 

AUTHOR

getwc() was developed by OSF and HP. 

SEE ALSO

fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). 

STANDARDS CONFORMANCE

getwc(): XPG4

fgetwc(): XPG4

getwchar(): XPG4

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996