C++ I/O Notes

This file is not complete or, necessarily, correct. Do not rely on its contents. Please mail me any corrections or suggestions..

State Bits

Bit	Input	Output
failbit	Set when an input operation fails to read the expected characters. For example, if a multi-character get() operation reads no characters (either through error or because the end of file is reached before any characters are read) then failbit is set. As another example, formatted input using >> would set failbit (but not eofbit) if it encountered sequence of characters which was invalid for the type being input. The rule appears to be that failbit is set if the right characters were not available (i.e. if either the wrong characters were available, or if no characters were available).	Set when an output operation fails to output the expected characters. For example, formatted output using << might set failbit (and badbit) if it could not write to a file because there was no disc space available. (In the GNU implementation, errno appears to be set appropriately, but who knows if this is guaranteed?)
eofbit	Set when any attempt is made to read at end of file. failbit might NOT be set - for example a multi-character get() operation which reads several characters but does not fill the available space because of end of file being reached will set eof but not fail.	Should not be set on output streams.
badbit		This is set for (at least) output operations which fail due to some problem with the underlying file. The GNU documentation says that this bit is set when the stream is "unusable". Presumably the intent is that once this bit becomes set, all bets are off on that stream forever.

Bit

Input

Output

failbit

Set when an input operation fails to read the expected characters.

For example, if a multi-character get() operation reads no characters (either through error or because the end of file is reached before any characters are read) then failbit is set.

As another example, formatted input using >> would set failbit (but not eofbit) if it encountered sequence of characters which was invalid for the type being input.

The rule appears to be that failbit is set if the right characters were not available (i.e. if either the wrong characters were available, or if no characters were available).

Set when an output operation fails to output the expected characters.

For example, formatted output using << might set failbit (and badbit) if it could not write to a file because there was no disc space available. (In the GNU implementation, errno appears to be set appropriately, but who knows if this is guaranteed?)

eofbit

Set when any attempt is made to read at end of file.

failbit might NOT be set - for example a multi-character get() operation which reads several characters but does not fill the available space because of end of file being reached will set eof but not fail.

Should not be set on output streams.

badbit

This is set for (at least) output operations which fail due to some problem with the underlying file.

The GNU documentation says that this bit is set when the stream is "unusable". Presumably the intent is that once this bit becomes set, all bets are off on that stream forever.

State Test Operations

Operation	Description	Example
bool fail() const	Returns true if and only if "fail" or "bad" are set. Note that eofbit is not tested, so an input operation which (for example) read at least one character, but did not read all the characters expected due to reaching end of file, would result in fail() returning false.	if(cin.fail()) // handle error
operator void*() const	Returns a null pointer if fail() is true (i.e. if failbit or badbit are set) or an arbitrary non-null pointer otherwise. The same caveats as above apply.	if(cin) // handle success else // handle error
bool operator!() const	Returns the value of fail() (i.e. returns true if and only if failbit or badbit are set). The same caveats as above apply.	if(!cin) // handle error
bool eof() const	Returns true if eofbit is set, i.e. if an attempt was made to read a character at end of file.	if(cin.eof()) // handle end of file
bool bad() const	Returns true if badbit is set	if(cin.bad()) // handle failure
bool good() const	Returns true if all the state bits are zero.	if(cin.good()) // handle success
iostate rdstate() const	Returns the current state bits as a bitmap.	if(cin.rdstate() & ios_base::eofbit) // handle end of file

Other State Operations

Function	Description	Example
void clear(iostate state)	This function is used to set the stream state bits. The argument is constructed a bitwise OR of one or more of goodbit, badbit, eofbit and failbit. The default value for state is goodbit (which is actually 0). If an exception has been requested for a particular state, then an exception is thrown if the stream is/was in that state (XXX is or was???)	cin.clear();
void setstate(iostate state)	Adds the bits in state to the current stream state.	cin.setstate(ios_base::failbit);

Function

Description

Example

void clear(iostate state)

This function is used to set the stream state bits. The argument is constructed a bitwise OR of one or more of goodbit, badbit, eofbit and failbit. The default value for state is goodbit (which is actually 0).

If an exception has been requested for a particular state, then an exception is thrown if the stream is/was in that state (XXX is or was???)

cin.clear();

void setstate(iostate state)

Adds the bits in state to the current stream state.

cin.setstate(ios_base::failbit);

Pending Queries

When can "bad" be set on input?

When can "fail" but not "bad" be set on output?

RJK | Contents