UNGETC(3s,L)                AIX Technical Reference                UNGETC(3s,L)



-------------------------------------------------------------------------------
ungetc, ungetwc



PURPOSE

Pushes a character or a wide character back into input stream.

LIBRARY

Standard I/O Library (libc.a)

SYNTAX

#include <stdio.h>

int ungetc (c, stream)
int c;
FILE *stream;

wchar_t ungetwc (c, iop)
wchar_t c;
FILE *iop;

DESCRIPTION

The ungetc subroutine inserts the character specified by the c parameter into
the buffer associated with the input stream specified by the stream parameter.
This causes the next call to the getc subroutine to return c.  ungetc returns
c, and leaves the stream file unchanged.

If the c parameter is EOF, then the ungetc subroutine does not place anything
in the buffer and a value of -1 is returned.

You can always push one character back onto a stream, provided that something
has been read from the stream or setbuf has been called.  The fseek subroutine
erases all memory of inserted characters.

The ungetwc subroutine pushes the wide character specified by c back onto the
input stream pointed to by stream.  The pushed-back wide characters are
returned by subsequent reads on that stream in the reverse order of their
pushing.  A successful intervening call (with the stream pointed to by stream)
to a file positioning subroutine (fseek, fsetopts or rewind) discards any
pushed-back wide characters for the stream.  The external storage corresponding
to the stream is unchanged.

One wide character of push-back is guaranteed.  If the ungetwc subroutine is
called too many times on the same stream without an intervening read or file
positioning operation on that stream, the operation may fail.





Processed November 7, 1990       UNGETC(3s,L)                                 1

UNGETC(3s,L)                AIX Technical Reference                UNGETC(3s,L)



If the value of c equals that of the macro WEOF, the operation fails and the
input stream is unchanged.

A successful call to the ungetwc subroutine clears the end-of-file 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 characaters were pushed back.  For a text stream, the value of
its file position indicator after a successful call to the ungetwc subroutine
is unspecified until all pushed-back wide characters are read or discarded.
For a binary stream, the value of its file position indicator is undefined; if
the value was zero before a call, it is indeterminate after the call.

RETURN VALUE

The ungetc subroutine returns -1 if it cannot insert the character.

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

RELATED INFORMATION

In this book:  "fseek, rewind, ftell,"  "getc, fgetc, getchar, getw, getwc,
fgetwc, getwchar,"  "setbuf, setvbuf," and "stdio."
































Processed November 7, 1990       UNGETC(3s,L)                                 2