Skip to content
Tutorials Center
My learning

Topics

C Reference ยท stdio.h

C ungetc() function

Reference for C ungetc(): push one character back onto an input stream so the next read returns it again, with limits, return values and typical parsers.

ungetc() pushes one character back onto an input stream, so the next read from that stream returns it again. It is the standard tool for "look ahead": read a character, find out that it does not belong to the token you are parsing, and give it back to whoever reads next.

The pushed-back character lives in the stream's buffer, not in the file. The file on disk is never changed, and a successful push-back clears the end-of-file flag.

C
#include <stdio.h>

int ungetc(int c, FILE *stream);

Try it

C Reading a number and pushing back the delimiter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C Peeking at the next character

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Syntax

C
int ungetc(int c, FILE *stream);
Name Description
c The character to push back, converted to unsigned char. Pushing back EOF is allowed to fail and does nothing.
stream An input stream that was opened for reading.

Returns: the character pushed back (as an unsigned char converted to int) on success, or EOF on failure. On failure the stream is unchanged.

Errors / undefined behavior: the standard guarantees only one character of push-back. A second ungetc() without an intervening read, seek or flush may fail and return EOF. Calling it on a stream that is not open for reading is an error. Passing a NULL or closed stream is undefined behavior.

Usage notes

  • One character is guaranteed. glibc happens to allow more, but portable code must not push back two characters in a row. If your parser needs more look-ahead, store the characters in your own buffer.
  • The file is not modified. Only the in-memory stream state changes. You can even push back a character that was never in the file.
  • Position functions. After a successful push-back, ftell() is decreased by one on a text stream when the position is meaningful, and fseek(), rewind() and fflush() discard the pushed-back character. For a text stream the exact position after pushing back at the start of the file is unspecified.
  • Clears EOF. A successful ungetc() clears the stream's end-of-file indicator, so feof() is false afterwards. It does not clear the error indicator.
  • Works on stdin. That makes it handy for interactive tokenizers, as in the first example. It does not work with data that is not buffered by the stream (for example if you read with read() directly).
  • Pair it with int variables. Store the result of getchar() in an int, never a char, so EOF stays distinguishable (see EOF and BUFSIZ).
  • Not a substitute for scanf formats. scanf does its own look-ahead and may push back one character after a failed conversion.
  • Complexity: constant time.