cpp/io/basic filebuf/pbackfail

This protected virtual function is called by the public functions and  (which, in turn, are called by  and ).

@1@ The caller is requesting that the get area is backed up by one character ( is called with no arguments), in which case, this function re-reads the file starting one byte earlier and decrements, e.g. by calling. @2@ The caller attempts to putback a different character from the one retrieved earlier ( is called with the character that needs to be put back), in which case
 * @a@ First, checks if there is a putback position, and if there isn't, backs up the get area by re-reading the file starting one byte earlier.
 * @a@ Then checks what character is in the putback position. If the character held there is already equal to, as determined by , then simply decrements.
 * @b@ Otherwise, if the buffer is allowed to modify its own get area, decrements and writes  to the location pointed to gptr after adjustment.

This function never modifies the file, only the get area of the in-memory buffer.

If the file is not open (, this function returns immediately.

Return value
on success except if was, in which case  is returned.

on failure.