ungetwc(S)

ungetwc -- push wide-character code back into input stream

Syntax

cc . . . -lc

#include <stdio.h>
#include <wchar.h>

wint_t ungetwc(wint_t wc, FILE *stream);

Description

ungetwc(S) pushes the wide-character code wc back onto the stream pointed to by stream. When that stream is read subsequently, these pushed back characters are returned in a first in, last out order. Before any pushed back characters are read again from the stream, if a file-positioning routine (such as fseek(S), fsetpos(S), or rewind(S)) is called on stream successfully, these pushed back characters are discarded. This does not change the external storage corresponding to the stream, however.

Pushing back one character is guaranteed. If too many characters are pushed back by ungetwc( ) without an intervening read or file-positioning operation on the stream, the pushing back may fail.

ungetwc( ) will not push back an end-of-file macro, WEOF. If wc has the value of WEOF, ungetwc( ) fails, without changing the input stream.

When ungetwc( ) returns successfully, it clears the end-of-file indicator for the stream and decrements the file-position indicator by one, or more if wc is a multibyte character. If the value of the file position indicator was zero before the call to ungetwc( ), the position indicator is meaningless after the call. After all pushed back characters are read or discarded, the file-position indicator for the stream is restored to its value immediately before these characters were pushed back.

Return values

The wide-character code corresponding to the pushed back character is returned by ungetwc( ) on successful return. Otherwise WEOF is returned.

Diagnostics

If the following is true, ungetwc( ) fails:

[EILSEQ]: The character sequence is not valid or the wide-character code wc does not represent a valid character.

Standards conformance