ungetc() Function

The ungetc() function in C stdio.h allows you to push a character back onto an input stream so that it will be returned by the next input operation. This is useful for situations where you need to “undo” a character read from a stream without altering the underlying file content.

Syntax of ungetc()

</>
Copy
int ungetc(int character, FILE *stream);

Parameters

ParameterDescription
characterThe integer promotion of the character to be put back, internally converted to an unsigned char.
streamPointer to the FILE object representing the input stream.

The function virtually returns a character to the input stream, effectively reversing a previous read operation by decrementing the internal file position. It clears the end-of-file indicator if set and, in binary mode, adjusts the file position accordingly. Note that the physical file remains unchanged and that multiple calls to ungetc() may not be portable across all implementations.

Return Value

On success, ungetc() returns the character that was pushed back (as an int). If the operation fails, it returns EOF.

Examples for ungetc()

Example 1: Reverting a Single Character Read from a File

This example demonstrates how to read a character from a file, then push it back onto the stream so that it can be read again.

Program

</>
Copy
#include <stdio.h>

int main() {
    FILE *fp = fopen("example.txt", "r");
    if (fp == NULL) {
        printf("Failed to open file.\n");
        return 1;
    }

    int ch = fgetc(fp);
    printf("First read: %c\n", ch);

    ungetc(ch, fp);

    int ch_again = fgetc(fp);
    printf("After ungetc, read again: %c\n", ch_again);

    fclose(fp);
    return 0;
}

Explanation:

  1. A file named example.txt is opened for reading.
  2. The first character is read using fgetc() and printed.
  3. ungetc() pushes the character back onto the stream.
  4. The next call to fgetc() retrieves the same character, demonstrating that the read operation was reversed.

Program Output:

First read: H
After ungetc, read again: H

Example 2: Handling Failure When Pushing Back EOF

This example illustrates the behavior of ungetc() when attempting to push back EOF, which should fail.

Program

</>
Copy
#include <stdio.h>

int main() {
    FILE *fp = fopen("example.txt", "r");
    if (fp == NULL) {
        printf("Failed to open file.\n");
        return 1;
    }

    int result = ungetc(EOF, fp);
    if (result == EOF) {
        printf("ungetc failed as expected when passing EOF.\n");
    } else {
        printf("Unexpected success.\n");
    }

    fclose(fp);
    return 0;
}

Explanation:

  1. The file example.txt is opened for reading.
  2. ungetc() is called with EOF as the character, which is not allowed.
  3. The function returns EOF, indicating failure.
  4. An appropriate error message is printed.

Program Output:

ungetc failed as expected when passing EOF.

Example 3: Using Multiple ungetc() Calls (Non-Portable Behavior)

This example demonstrates pushing back two characters consecutively. Note that support for multiple ungetc() calls is implementation-dependent and may not work on all systems.

Program

</>
Copy
#include <stdio.h>

int main() {
    FILE *fp = fopen("example.txt", "r");
    if (fp == NULL) {
        printf("Failed to open file.\n");
        return 1;
    }

    int firstChar = fgetc(fp);
    int secondChar = fgetc(fp);

    /* Push the characters back in reverse order */
    ungetc(secondChar, fp);
    ungetc(firstChar, fp);

    int r1 = fgetc(fp);
    int r2 = fgetc(fp);

    printf("After multiple ungetc calls: %c %c\n", r1, r2);

    fclose(fp);
    return 0;
}

Explanation:

  1. The file example.txt is opened for reading and two characters are read sequentially.
  2. Both characters are pushed back onto the stream using two consecutive calls to ungetc().
  3. The subsequent reads retrieve the characters in the order they were pushed back, provided the implementation supports multiple ungetc() calls.
  4. A message is printed displaying the two characters read after the unget operations.

Program Output:

After multiple ungetc calls: H e