### ungetwc -- Push Wide Character onto Input Stream

#### Format

>     #include <wchar.h>
>     wint_t ungetwc(wint_t wc, FILE *stream);

Language Level: XPG4
ungetwc pushes the wide character by wc back onto the input stream. The pushed-back wide characters will be returned by subsequent reads on that stream in the reverse order of their pushing. A successful intervening call (on the stream) to a file positioning function (fseek, fsetpos, or rewind) discards any pushed-back wide characters for the stream.

The external storage corresponding to the stream is unchanged. There is always at least one wide character of push-back.

If the value of wc is WEOF, the operation fails and the input stream is unchanged.

A successful call to the ungetwc function clears the EOF indicator for the stream. The value of the file position indicator for the stream after reading or discarding all pushed-back wide characters is the same as it was before the wide characters were pushed back.

For a text stream, the file position indicator is backed up by one wide character. This affects ftell, fflush, fseek (with SEEK_CUR), and fgetpos.

For a binary stream, the position indicator is unspecified until all characters are read or discarded, unless the last character is pushed back, in which case the file position indicator is backed up by one wide character. This affects ftell, fseek (with SEEK_CUR), fgetpos, and fflush.

After calling ungetwc, flush the buffer or reposition the stream pointer before calling a read function for the stream, unless EOF has been reached. After a read operation on the stream, flush the buffer or reposition the stream pointer before calling ungetwc.

Note:

1. Under IBM C and C++ Compilers, only 1 wide character may be pushed back.
2. The position on the stream after a successful call to ungetwc is one wide character prior to the current position.

Return Value
ungetwc returns the wide character pushed back after conversion, or WEOF if the operation fails.

Example

fflush -- Write Buffer to File
fseek -- Reposition File Position
fsetpos -- Set File Position
getwc -- Read Wide Character from Stream
putwc -- Write Wide Character
ungetc -- Push Character onto Input Stream
_ungetch -- Push Character Back to Keyboard
<wchar.h>