<!--
    Licensed to the Apache Software  Foundation (ASF) under one or more
    contributor  license agreements.  See  the NOTICE  file distributed
    with  this  work  for  additional information  regarding  copyright
    ownership.   The ASF  licenses this  file to  you under  the Apache
    License, Version  2.0 (the  License); you may  not use  this file
    except in  compliance with the License.   You may obtain  a copy of
    the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the  License is distributed on an  "AS IS" BASIS,
    WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
    implied.   See  the License  for  the  specific language  governing
    permissions and limitations under the License.

    Copyright 1999-2007 Rogue Wave Software, Inc.
-->

<HTML>
<HEAD>
<TITLE>About Flags</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="29.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="29-2.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library User's Guide</B></DIV>
<H2>29.1 About Flags</H2>
<A NAME="idx726"><!></A>
<P>It probably comes as no surprise that streams have an error state. When an error occurs, flags are set in the state according to the general category of the error. Flags and their error categories are summarized in <A HREF="29-1.html#Table&nbsp;30">Table&nbsp;30</A>:</P>
<A NAME="idx727"><!></A>
<H4><A NAME="Table&nbsp;30">Table&nbsp;30: Flags and corresponding error categories&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>iostate flag</B>
</td><td valign=top><B>Error category</B>
</td></tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ios_base::goodbit</SAMP></P>
</td><td valign=top><P CLASS="TABLE">Everything's fine</P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ios_base::eofbit</SAMP></P>
</td><td valign=top><P CLASS="TABLE">An input operation reached the end of an input sequence</P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ios_base::failbit</SAMP></P>
</td><td valign=top><P CLASS="TABLE">An input operation failed to read the expected character, or</P>
<P CLASS="TABLE">an output operation failed to generate the desired characters</P>
</td></tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ios_base::badbit</SAMP></P>
</td><td valign=top><P CLASS="TABLE">Indicates the loss of integrity of the underlying input or output sequence or some other serious error</P>
</td></tr>
</TABLE>
<A NAME="idx728"><!></A>
<P>Note that the flag <SAMP>std::ios_base::goodbit</SAMP> is not represented by any one bit; its value, <SAMP>0</SAMP>, indicates the absence of any error flag. This means the stream is OK. By convention, all input and output operations have no effect once the stream state is different than 0.</P>
<A NAME="idx729"><!></A>
<P>There are several situations when both <SAMP>eofbit</SAMP> and <SAMP>failbit</SAMP> are set; however, the two have different meanings and do not always occur in conjunction. The flag <SAMP>eofbit</SAMP> is set when there is an attempt to read past the end of an input sequence. This occurs in the following two typical examples:</P>
<OL>
<LI><P CLASS="LIST">Assume the extraction happens character-wise. Once the last character is read, the stream is still in good state; <SAMP>eofbit</SAMP> is not yet set. Any subsequent extraction, however, is considered an attempt to read past the end of the input sequence. Thus, <SAMP>eofbit</SAMP> is set. (Later, we'll see that <SAMP>failbit</SAMP> is set as well.)</P></LI>
<LI><P CLASS="LIST">If you do not read character-wise, but extract an integer or a string, for example, you always read past the end of the input sequence. This is because the input operators read characters until they find a separator, or hit the end of the input sequence. Consequently, if the input contains the sequence <SAMP>... 912749&lt;eof&gt;</SAMP> and an integer is extracted, the <SAMP>eofbit</SAMP> flag (but not <SAMP>failbit</SAMP>) is set.  </P></LI>
</OL>
<A NAME="idx730"><!></A>
<P>The flag <SAMP>std::ios_base::failbit</SAMP> is set as the result of a read or write operation that fails. For example, if you try to extract an integer from an input sequence containing only white spaces, the extraction of an integer fails, and the <SAMP>failbit</SAMP> is set. Let's see whether <SAMP>failbit</SAMP> would be set in the previous examples:</P>
<OL>
<LI><P CLASS="LIST">After reading the last available character, the extraction not only reads past the end of the input sequence; it also fails to extract the requested character. Hence, <SAMP>failbit</SAMP> is set in addition to <SAMP>eofbit</SAMP>.</P></LI>
<LI><P CLASS="LIST">In this case, the result is different. Although the end of the input sequence is reached by extracting the integer, the input operation does not fail and the desired integer is indeed read. In this situation only the <SAMP>eofbit</SAMP> is set.</P></LI>
</OL>
<A NAME="idx731"><!></A>
<P>In addition to these input and output operations, there are other situations that can trigger failure. For example, file streams set <SAMP>failbit</SAMP> if the associated file cannot be opened (see <A HREF="30-2.html#3022">Section&nbsp;30.2.2</A>).</P>
<A NAME="idx732"><!></A>
<P>The flag <SAMP>std::ios_base::badbit</SAMP> indicates problems with the underlying stream buffer. These problems could be:</P>
<UL>
<LI><P CLASS="LIST"><B><I>Memory shortage</I></B>. There is no memory available to create the buffer, or the buffer has size <SAMP>0</SAMP> for other reasons (such as being provided from outside the stream), or the stream cannot allocate memory for its own internal data, as with <SAMP>std::ios_base::iword()</SAMP> and <SAMP>std::ios_base::pword()</SAMP>.</P></LI>
<LI><P CLASS="LIST"><B><I>The underlying stream buffer throws an exception</I></B>. The stream buffer might lose its integrity, as in memory shortage, or code conversion failure, or an unrecoverable read error from the external device. The stream buffer can indicate this loss of integrity by throwing an exception, which is caught by the stream and results in setting the <SAMP>badbit</SAMP> in the stream's state.</P></LI>
</UL>
<P>Generally, you should keep in mind that <SAMP>badbit</SAMP> indicates an error situation that is likely to be unrecoverable, whereas <SAMP>failbit</SAMP> indicates a situation that might allow you to retry the failed operation. The flag <SAMP>eofbit</SAMP> simply indicates the end of the input sequence.</P>
<P>What can you do to check for such errors? You have two possibilities for detecting stream errors:</P>
<UL>
<LI><P CLASS="LIST">You can declare that you want to have an exception raised once an error occurs in any input or output operation.</P></LI>
<LI><P CLASS="LIST">You can actively check the stream state after each input or output operation.</P></LI>
</UL>
<P>We explore these possibilities in the next two sections.</P>

<BR>
<HR>
<A HREF="29.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="29-2.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
    _uacct = "UA-1775151-1";
    urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->

</BODY>
</HTML>