std::ungetc

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Input/output library

I/O manipulators

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

strstreambuf (deprecated)

Streams

Abstractions

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

File I/O

basic_ifstream

basic_ofstream

basic_fstream

String I/O

basic_istringstream

basic_ostringstream

basic_stringstream

Array I/O

istrstream (deprecated)

ostrstream (deprecated)

strstream (deprecated)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

 

C-style I/O

Functions
File access
fopen freopen fclose fflush	fwide setbuf setvbuf
Direct input/output
fread
fwrite
Unformatted input/output
fgetc fgets fputc fputs getchar gets (until C++14) putchar puts ungetc	fgetwc fgetws fputwc fputws getwchar putwchar ungetwc
Formatted input/output
scanffscanfsscanf vscanfvfscanfvsscanf (C++11)(C++11)(C++11) printffprintfsprintfsnprintf (C++11) vprintfvfprintfvsprintfvsnprintf (C++11)	wscanffwscanfswscanf vwscanfvfwscanfvswscanf (C++11)(C++11)(C++11) wprintffwprintfswprintf vwprintfvfwprintfvswprintf
File positioning
ftell
fgetpos
fseek
fsetpos
rewind
Error handling
clearerr
feof
ferror
perror
Operations on files
remove
rename
tmpfile
tmpnam

 

Defined in header <cstdio>
int ungetc( int ch, std::FILE *stream );

If ch does not equal EOF, pushes the character ch (reinterpreted as unsigned char) into the input buffer associated with the stream stream in such a manner than subsequent read operation from stream will retrieve that character. The external device associated with the stream is not modified.

Stream repositioning operations std::fseek, std::fsetpos, and std::rewind discard the effects of ungetc.

If ungetc is called more than once without an intervening read or repositioning, it may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined). If multiple successful ungetc were performed, read operations retrieve the pushed-back characters in reverse order of ungetc

If ch equals EOF, the operation fails and the stream is not affected.

A successful call to ungetc clears the end of file status flag std::feof.

A successful call to ungetc on a binary stream decrements the stream position indicator by one (the behavior is indeterminate if the stream position indicator was zero).

A successful call to ungetc on a text stream modifies the stream position indicator in unspecified manner but guarantees that after all pushed-back characters are retrieved with a read operation, the stream position indicator is equal to its value before ungetc.

Parameters

ch	-	character to be pushed into the input stream buffer
stream	-	file stream to put the character back to

Return value

On success ch is returned.

On failure EOF is returned and the given stream remains unchanged.

Notes

The size of the pushback buffer varies in practice from 4k (Linux, MacOS) to as little as 4 (Solaris) or the guaranteed minimum 1 (HPUX, AIX)

The apparent size of the pushback buffer may be larger if the character that is pushed back equals the character existing at that location in the external character sequence (the implementation may simply decrement the read file position indicator and avoid maintaining a pushback buffer)

Example

demonstrates the use of ungetc in its original purpose: implementing scanf

Run this code

#include <cctype>
#include <cstdio>
 
void demo_scanf(const char* fmt, std::FILE* s) {
    if(*fmt == '%') {
        switch(*++fmt) {
            case 'u': {
                int c;
                while(std::isspace(c=std::getc(s))) {} // skip leading white space
                unsigned int num = 0;
                while(std::isdigit(c)) {
                    num = num*10 + c-'0';
                    c = std::getc(s);
                }
                std::printf("%%u scanned %u\n", num);
                std::ungetc(c, s); // reprocess the non-digit
            }
            case 'c': {
                int c = std::getc(s);
                std::printf("%%c scanned '%c'\n", c);
            }
        }
    }
}
 
int main()
{
    std::FILE* f = std::fopen("input.txt", "w+");
    std::fputs("123x", f);
    std::rewind(f);
    demo_scanf("%u%c", f);
    std::fclose(f);
}

Output:

%u scanned 123
%c scanned 'x'

See also

fgetcgetc	gets a character from a file stream (function)
C documentation for ungetc