[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


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 ( CharacterStream)
int Character;
FILE *Stream;

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

Description

The ungetc and ungetwc subroutines insert the character specified by the Character parameter (converted to an unsigned character in the case of the ungetc subroutine) into the buffer associated with the input stream 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, provided that something has been 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 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


Character Specifies a character.
Stream Specifies the input stream.

Return Values

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

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

Other wide character I/O subroutines: fgetwc subroutine, fgetws subroutine, fputwc subroutine, fputws subroutine, getwc subroutine, getwchar subroutine, getws subroutine, putwc subroutine, putwchar subroutine, putws subroutine.

Related standard I/O subroutines: fdopen subroutine, fgets subroutine, fopen subroutine, fprintf subroutine, fputc subroutine, fputs subroutine, fread subroutine, freopen subroutine, fwrite subroutine, gets subroutine, printf subroutine, putc subroutine, putchar subroutine, puts subroutine, putw subroutine, sprintf subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character Input/Output Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]