4.67 ungetwc—push wide character data back into a stream

Synopsis

     #include <stdio.h>
     #include <wchar.h>
     wint_t ungetwc(wint_t wc, FILE *stream);
     
     wint_t _ungetwc_r(struct _reent *reent, wint_t wc, FILE *stream);
     

Description
ungetwc is used to return wide characters back to stream to be read again. If wc is WEOF, the stream is unchanged. Otherwise, the wide character wc is put back on the stream, and subsequent reads will see the wide chars pushed back in reverse order. Pushed wide chars are lost if the stream is repositioned, such as by fseek, fsetpos, or rewind.

The underlying file is not changed, but it is possible to push back something different than what was originally read. Ungetting a character will clear the end-of-stream marker, and decrement the file position indicator. Pushing back beyond the beginning of a file gives unspecified behavior.

The alternate function _ungetwc_r is a reentrant version. The extra argument reent is a pointer to a reentrancy structure.

Returns
The wide character pushed back, or WEOF on error.

Portability
C99