<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>N2503 Indicating iostream failures with system_error</title>
    <base href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/" />
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
<style type="text/css">
  p {text-align:justify}
  li {text-align:justify}
  ins {background-color:#FFFF99}
  del {background-color:#FF9999}
    </style>

  <body>
    Document Number: N2503=08-0013<br />
    2008-02-04<br />
    Alisdair Meredith &lt;<a href="mailto:alisdair.meredith@codegear.com">alisdair.meredith@codegear.com</a>><br />
    Beman Dawes &lt;<a href="mailto:bdawes@acm.org">bdawes@acm.org</a>><br />
    
    <h1>Indicating iostream failures with <code>system_error</code></h1>
    
    <h2>Problem Description</h2>
    
    <p>
    The standard library now supplies library support for portable reporting
    of errors from the host operating system. See 19.4.5 Class system_error
    [syserr.syserr].  That API allows exception classes used to report host
    system failures to be derived from a new library exception type, <code>
    system_error</code>, which encapsulates failure information returned from
    the host operating system.</p>
    <p>
    Failures in the iostreams portion of the standard library may indicate
    failure with exceptions. The exception thrown in such cases is
    <code>ios_base::failure</code>, which is publicly derived from the
    standard library class <code>exception</code>.
    </p>
    <p>
    As iostream failures are typically a runtime problem detected by the
    host system, we would like this exception to derive from
     <code>system_error</code>.
    </p>
    
    
    <h2>Proposed Solution</h2>

    <p>
    Library clause 17.4.4.7 grants implementors permission to derive
    classes from classes other than the specified base, so long as
    
    <li>the additional 'intermediate' classes ultimately derive from the
    specified base</li>
    
    <li>the name of any 'intermediate' class is reserved to the
    implementation</li>
    
    </p>
    <p>
    Note that all standard library class names are by definition <em>reserved
    for the implementation</em>. In particular, <code>system_error</code>
    and <code>runtime_error</code> are names reserved for the implementation
    so a conforming (but surprising) implementation of
    <code>ios_base::failure</code> in C++03 might derive from
    <code>runtime_error</code>.
    </p>
    <p>
    Therefore, it is proposed that <code>ios_base::failure</code> derive from
    <code>system_error</code> and that the implementation makes a best effort
    to record the fault reported by the host system.
    </p>

    <h2>Alternative Proposal</h2>
    <p>
    Note that Benjamin Kosnik proposes a more extensive reworking of standard
    library exceptions in <a href="../2007/n2309.html">n2309</a>.
    </p>

    <h2>Proposed Changes to the Working Paper</h2>

    <p>
      Change 27.4.2.1.1 [ios::failure] as indicated:
    </p>
    <blockquote>
<pre><code>
namespace std {
  class ios_base::failure : public <del>exception</del><ins>system_error</ins> {
  public:
    explicit failure(const string& msg<ins>, error_code ec = posix_error::io_error</ins> );
    explicit failure(const char* msg<ins>, error_code ec = posix_error::io_error</ins> );
    <ins>failure(const string& msg, error_code::value_type ev, const error_category& ecat );</ins>
    <ins>failure(const char* msg, error_code::value_type ev, const error_category& ecat );</ins>
    virtual const char* what() const throw();
  };
}</code></pre>

<p>
The class failure defines the base class for the types of all objects thrown as exceptions, by functions in the iostreams
library, to report errors detected during stream buffer operations.
</p>
<code>explicit failure(const string& msg<ins>, error_code ec = posix_error::io_error</ins>);</code>
<p>
  <em>Effects:</em> Constructs an object of class <code>failure</code>.
</p>
<p>
  <em>Postcondition:</em> <code>code() == ec</code> and <code>strcmp(what(), msg.c_str()) == 0</code>
</p>

<p>
<code>explicit failure(const char* msg<ins>, error_code ec = posix_error::io_error</ins>);</code>
</p>
<p>
  <em>Effects:</em> Constructs an object of class <code>failure</code>.
</p>
<p>
  <em>Postcondition:</em> <code>code() == ec</code> and <code>strcmp(what(), msg ) == 0</code>
</p>
<p>
<ins><code>failure(const string& msg, error_code::value_type ev, const error_category& ecat);</code></ins>
</p>
<p>
  <ins><em>Effects:</em> Constructs an object of class <code>failure</code>.</ins>
</p>
<p>
  <ins><em>Postcondition:</em> <code>code() == error_code(ev, ecat)</code> and <code>strcmp(what(), msg.c_str()) == 0</code></ins>
</p>

<p>
<ins><code>failure(const char* msg, error_code::value_type ev, const error_category& ecat);</code></ins>
</p>
<p>
  <ins><em>Effects:</em> Constructs an object of class <code>failure</code>.</ins>
</p>
<p>
  <ins><em>Postcondition:</em> <code>code() == error_code(ev, ecat)</code> and <code>strcmp(what(), msg) == 0</code></ins>
</p>
<pre></pre>
    </blockquote>
    
    <p>
      Change 27.4.4.3p5 [iostate.flags] as indicated:
    </p>
    <blockquote>
      <em>Effects:</em> If <code>((state | (rdbuf() ? goodbit : badbit)) &
      exceptions()) == 0</code>, returns. Otherwise, the function throws an
      object <em>fail</em> of class <code>basic_ios::failure</code>
      (27.4.2.1.1), constructed with implementation defined argument values.
      <ins>
      <p>
      <em>Note:</em> Implementations are encouraged to report the original failure from the host system as the error code when throwing an exception.
      </p>
      </ins>
    </blockquote>

  </body>
</html>
