HP C/iX Library Reference Manual (30026-90004)

378 Chapter5
HP C/iX Library Function Descriptions
ungetc
ungetc
Pushes back a single character onto an open stream.
Syntax
#include <stdio.h>
int ungetc (int c , FILE * stream );
Parameters
c A single character to push back.
stream A pointer to an open stream.
Return Values
x The value of the argument c , indicating success.
EOF An error occurred.
Description
The ungetc function pushes the character specified by c (converted to an unsigned char)
back onto the input stream pointed to by
stream . The pushed-back character is returned
by subsequent reads on the stream in the reverse order of their pushing. A successful
intervening call to
stream to a file positioning function (fseek(), fsetpos(),orrewind())
discards any pushed-back characters for the stream. The external storage corresponding to
the stream is unchanged.
One character pushback is guaranteed. If the ungetc() function is called too many times
on the same stream without an intervening read or file positioning operation on that
stream, the operation may fail.
If the value of
c equals that of the macro EOF, the operation fails and the input stream is
unchanged.
A successful call to ungetc() 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
characters is the same as it was before the characters were pushed back.
For a text stream, the value of its file position indicator after a successful call to ungetc()
is unspecified until all pushed-back characters are read or discarded. For a binary stream,
its file position indicator is decremented by each successful call to ungetc(), if its value
was zero before the call, it is indeterminate after the call.
Examples
The following program reads one character from stdin, pushes it back onto stdin,
rereads the character, and checks to make sure that this character and the character
originally pushed back are the same. A message is printed on stdout stating the outcome