ungetc or ungetwc Subroutine

Purpose

Pushes a character back into the input stream.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h>

int ungetc ( Character,  Stream)
int Character;
FILE *Stream;

wint_t ungetwc (Character, Stream)
wint_t Character;
FILE *Stream;

Description

The ungetc and ungetwc subroutines insert the character that is specified by the Character parameter (converted to an unsigned character in the case of the ungetc subroutine) into the buffer that is associated with the input stream that is specified by the Stream parameter. This causes the next call to the getc or getwc subroutine to return the Character value. A successful intervening call (with the stream specified by the Stream parameter) to a file-positioning subroutine (fseek, fsetpos, or rewind) discards any inserted characters for the stream. The ungetc and ungetwc subroutines return the Character value, and leaves the file (in its externally stored form) specified by the Stream parameter unchanged.

You can always push one character back onto a stream, if something is read from the stream or the setbuf subroutine has been called. If the ungetc or ungetwc subroutine is called too many times on the same stream without an intervening read or file-positioning operation, the operation may not be successful. The fseek subroutine erases all memory of inserted characters.

The ungetc and ungetwc subroutines return a value of EOF or WEOF if a character cannot be inserted.

A successful call to the ungetc or ungetwc subroutine clears the end-of-file indicator for the stream that is specified by the Stream parameter. The value of the file-position indicator after all inserted characters are read or discarded is the same as before the characters were inserted. The value of the file-position indicator is decreased after each successful call to the ungetc or ungetwc subroutine. If its value was 0 before the call, its value is indeterminate after the call.

Parameters

Return Values

The ungetc and ungetwc subroutines return the inserted character if successful; otherwise, EOF or WEOF is returned, respectively.