Header boost/system/system_error.hpp

Introduction
Synopsis
Class system_error
    Members
Acknowledgements

Introduction

This header provides components used to report errors originating from the operating system or other low-level application program interfaces (API's). It is based on the Diagnostics portion of the TR2 filesystem proposal.

Synopsis

namespace boost
{
  namespace system
  {
    enum message_action { append_message, no_message };

    class system_error : public std::runtime_error
    {
    public:
      explicit system_error( error_code ec );

      system_error( error_code ec, const std::string & what_arg,
        message_action ma = append_message );

      system_error( error_code::value_type ev, error_category ecat );

      system_error( error_code::value_type ev, error_category ecat,
        const std::string & what_arg, message_action ma = append_message );

      virtual ~system_error() throw() {}

      const error_code & code() const throw();

      const char * what() const throw();

    private:
      error_code           m_error_code;      // for exposition only
      bool                 m_append_message;  // for exposition only
      mutable std::string  m_what;            // for exposition only
    };
  } // namespace system
} // namespace boost

Class system_error

Class system_error defines the type of an object that may be thrown as an exception to report errors originating from the operating system or other low-level API's, or used as a base class for more refined exception classes. It encapsulates an error_code object.

[Note: A single low-level class, rather than a higher level exception class hierarchy, is provided to allow users access to low-level error codes originating from the operating system or other low-level API's, and to accommodate the open-ended set of errors that may be reported by such API's. --end note.]

Class system_error Members

explicit system_error( error_code ec );

Effects: Constructs an object of class system_error.

Postcondition: code() == ec && *runtime_error::what() == '\0' && m_append_message.

system_error( error_code ec, const std::string & what_arg, message_action ma = append_message );

Effects: Constructs an object of class system_error.

Postcondition: code() == ec && std::string(runtime_error::what()) == what_arg && m_append_message == ma.

system_error( error_code::value_type ev, error_category ecat );

Effects: Constructs an object of class system_error.

Postcondition: code() == error_code(ev,ecat) && *runtime_error::what() == '\0' && m_append_message.

system_error( error_code::value_type ev, error_category ecat,
              const std::string & what_arg, message_action ma = append_message );

Effects: Constructs an object of class system_error.

Postcondition: code() == error_code(ev,ecat) && std::string(runtime_error::what()) == what_arg && m_append_message == ma.

const error_code & code() const throw();

Returns:  m_error_code

const char * what() const throw();

Returns: If !m_error_code || !m_append_message, runtime_error::what(). Otherwise, a string as if computed by:

m_what = runtime_error::what();
if ( !m_what.empty() ) m_what += ": ";
m_what += m_error_code.message();
return m_what.c_str();

Acknowledgements

Christopher Kohlhoff and Peter Dimov made important contributions to the design. Comments and suggestions were also received from Pavel Vozenilek, Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Jeremy Day, Bo Persson, Oliver Kowalke, and Oleg Abrosimov.

Last revised: 22 July, 2006

© Copyright Beman Dawes, 2006

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/ LICENSE_1_0.txt)