From cppreference.com
Defined in header
classfailure;The class std::ios_base::failure defines an exception object that is thrown on failure by the functions in the Input/Output library.
std::ios_base::failure may be defined either as a member class of
or as a synonym (typedef) for another class with equivalent functionality.
(since C++17)
Inheritance diagram
(until C++11)
Inheritance diagram
(since C++11)Member functions
(constructor)
constructs a new failure object with the given message
(public member function)operator=
replaces the failure object
(public member function)what
returns the explanatory string
(public member function)std::ios_base::failure::failure
explicitfailure(conststd::string&message); (1)(until C++11)explicitfailure(conststd::string&message,conststd::error_code&ec=std::io_errc::stream);(since C++11)explicitfailure(constchar*message,conststd::error_code&ec=std::io_errc::stream); (2) (since C++11)failure(constfailure&other); (3)(until C++11)failure(constfailure&other)noexcept;(since C++11)1,2) Constructs the exception object using message as explanation string which can later be retrieved using
. ec is used to identify the specific reason for the failure.(since C++11)
3) Copy constructor. Initialize the contents with those of other. If *this and other both have dynamic type std::ios_base::failure then std::strcmp(what(),other.what())==0.(since C++11)
Parameters
message - explanatory string ec - error code to identify the specific reason for the failure other - another failure to copy Notes
Because copying std::ios_base::failure is not permitted to throw exceptions, this message is typically stored internally as a separately-allocated reference-counted string. This is also why there is no constructor taking std::string&&: it would have to copy the content anyway.
std::ios_base::failure::operator=
failure&operator=(constfailure&other);(until C++11)failure&operator=(constfailure&other)noexcept;(since C++11)Assigns the contents with those of other. If *this and other both have dynamic type std::ios_base::failure then std::strcmp(what(),other.what())==0 after assignment.(since C++11)
Parameters
other - another exception object to assign with Return value
*this
std::ios_base::failure::what
virtualconstchar*what()constthrow();(until C++11)virtualconstchar*what()constnoexcept;(since C++11)Returns the explanatory string.
Return value
Pointer to an implementation-defined null-terminated string with explanatory information. The string is suitable for conversion and display as a
. The pointer is guaranteed to be valid at least until the exception object from which it is obtained is destroyed, or until a non-const member function (e.g. copy assignment operator) on the exception object is called.
The returned string is encoded with the ordinary literal encoding during constant evaluation.
(since C++26)Notes
Implementations are allowed but not required to override what().
Inherited from
Member functions
returns error code
(public member function of std::system_error)
[virtual]
returns an explanatory string
(virtual public member function of std::system_error)
Inherited from
Member functions
[virtual]
destroys the exception object
(virtual public member function of std::exception)
[virtual]
returns an explanatory string
(virtual public member function of std::exception)
Notes
Before the resolution of
, std::ios_base::failure declared a destructor without throw(), where
was declared with throw()
. This means the std::ios_base::failure::~failure() had a weaker exception specification. The resolution is to remove that declaration so that the non-throwing exception specification is kept.
targets the same defect and its resolution is to add throw() to the declaration of std::ios_base::failure::~failure(). That resolution was not applied due to the conflict between the two resolutions.
The non-throwing exception specification is now applied
globally across the standard library
, so the destructors of standard library classes are not declared with throw() or noexcept.
Example
Run this code
#include<fstream>#include<iostream>intmain(){std::ifstreamf("doesn't exist");try{f.exceptions(f.failbit);}catch(conststd::ios_base::failure&e){std::cout<<"Caught an ios_base::failure.\n"<<"Explanatory string: "<<e.what()<<'\n'<<"Error code: "<<e.code()<<'\n';}}Possible output:
Caught an ios_base::failure. Explanatory string: ios_base::clear: unspecified iostream_category error Error code: iostream:1 Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 the constructor overload (1) initialized the base class
with msg, but the base class does not have a matching constructor corresponding
description removed
C++98 std::ios_base::failure declared a destructor without throw()removed the destructor declaration See also