usr/src/lib/libc/stdio/ungetc.3

.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)ungetc.3    6.6 (Berkeley) %G%
.\"
.Dd
.Dt UNGETC 3
.Os
.Sh NAME
.Nm ungetc
.Nd un-get character from input stream
.Sh SYNOPSIS
.Fd #include <stdio.h>
.Ft int
.Fn ungetc "int c" "FILE *stream"
.Sh DESCRIPTION
The
.Fn ungetc
function pushes the character
.Fa c
(converted to an unsigned char)
back onto the input stream pointed to by
.Fa stream .
The pushed-backed characters will be returned by subsequent reads on the
stream (in reverse order).
A successful intervening call, using the same stream, to one of the file
positioning functions
.Po
.Xr fseek 3 ,
.Xr fsetpos 3 ,
or
.Xr rewind 3
.Pc
will discard the pushed back characters.
.Pp
One character of push-back is guaranteed,
but as long as there is
sufficient memory, an effectively infinite amount of pushback is allowed.
.Pp
If a character is successfully pushed-back,
the end-of-file indicator for the stream is cleared.
.Sh RETURN VALUES
The
.Fn ungetc
function
returns
the character pushed-back after the conversion, or
.Dv EOF
if the operation fails.
If the value of the argument
.Fa c
character equals
.Dv EOF ,
the operation will fail and the stream will remain unchanged.
.Sh SEE ALSO
.Xr getc 3 ,
.Xr fseek 3 ,
.Xr setvbuf 3
.Sh STANDARDS
The
.Fn ungetc
function conforms to
.St -ansiC .