ungetc, ungetwc - Push a byte or wide-character code back
into the input stream
#include <stdio.h>
int ungetc(
int c,
FILE *stream ); #include <wchar.h>
wint_t ungetwc(
wint_t wchar,
FILE *stream );
For the ungetwc() function, application developers may
want to specify an #include statement for <stdio.h> before
the one for <wchar.h> if programs are being developed for
multiple platforms. The additional #include statement is
not required on Tru64 UNIX systems or by ISO or X/Open
standards, but may be required on other vendors' systems
that conform to these standards.
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
ungetc(), ungetwc(): ISO C, XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies a byte to be inserted into the input stream.
Specifies the input stream. Specifies a wide-character
code.
The ungetc() function converts the byte specified by the c
parameter into an unsigned char and inserts it into the
buffer associated with the input stream specified by the
stream parameter. This causes the next call to the getc()
function to return c.
If the c parameter has a value equal to EOF, the ungetc()
function does not place anything in the buffer and the
input stream is unchanged.
The ungetwc() function inserts the wide character specified
by wchar into the buffer associated with the input
stream. The wide character may consist of one or more
bytes. This causes the next call to the getwc() function
to return the value of the wchar parameter.
If the ungetwc() wchar parameter is WEOF, the ungetwc()
function does not place anything in the buffer and the
input stream is unchanged.
A call to one of the file-positioning functions (fseek(),
fsetpos(), or rewind()), if it uses the same stream and
intervenes between a call to ungetc() or ungetwc() and
getc() or getwc(), discards any pushed back bytes for the
stream. The value of the file-position indicator after
reading or discarding pushed-back bytes will be the same
as it was before the bytes were pushed back.
A successful call to ungetc() or ungetwc() clears the endof-file
indicator and decrements the file-position indicator
for the stream. If the value of the file-position
indicator is zero before the call, the value is indeterminate
after the call. These functions do not have any
effect on the external storage corresponding to the
stream.
One character of push back is guaranteed (this corresponds
to one byte for ungetc()) and one or more bytes for
ungetwc()); however, if one of these functions is called
too many times on the same stream without an intervening
read or file-positioning operation on that stream, industry
standards specify that the functions may fail. (Applications
do not encounter this failure on Tru64 UNIX systems.
However, results are unpredictable if applications
intermix calls to ungetc() and ungetwc() on the same
stream.)
On successful insertion of the converted byte into the
stream, the ungetc() function returns the value of c.
Otherwise, the function returns EOF.
On successful insertion of the converted wide character
into the stream, the ungetwc() function returns the value
of wchar. Otherwise, the function returns WEOF.
If the following condition occurs, the ungetwc() function
sets errno to the corresponding value: An invalid byte
sequence is detected, or a wide-character code does not
correspond to a valid single-byte or multibyte character
in the current locale.
Functions: fseek(3), getc(3), getwc(3), setbuf(3)
Standards: standards(5)
ungetc(3)
[ Back ] | 