Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.

Boost Exception

diagnostic_information

#include <boost/exception/diagnostic_information.hpp> 
#include <boost/exception_ptr.hpp> 

namespace
boost
    {
    template <class E>
    std::string diagnostic_information( E const & e );
    
    std::string diagnostic_information( exception_ptr const & p );
    }

Returns:

A string value that contains varying amount of implementation-specific diagnostic information about the passed object:

  • If E can be statically converted to boost::exception, the returned value contains the string representations of all error_info objects stored in the boost::exception through operator<<, along with other diagnostic information relevant to the exception. If e can be dynamically converted to std::exception, the returned value also contains the what() string.
  • Otherwise, if E can be statically converted to std::exception:
    • if e can be dynamically converted to boost::exception, the returned value is the same as if E could be statically converted to boost::exception;
    • otherwise the returned value contains the what() string.
  • Otherwise, the boost::diagnostic_information template is not available.

The string representation of each error_info object is deduced by a function call that is bound at the time the error_info<Tag,T> template is instantiated. The following overload resolutions are attempted in order:

  1. Unqualified call to to_string(x), where x is of type error_info<Tag,T> (the return value is expected to be of type std::string.)
  2. Unqualified call to to_string(x.value()) (the return value is expected to be of type std::string.)
  3. Unqualified call to s << x.value(), where s is a std::ostringstream.

The first successfully bound function is used at the time diagnostic_information is called; if all 3 overload resolutions are unsuccessful, the system is unable to convert the error_info object to string, and an unspecified stub string value is used without issuing a compile error.

The exception_ptr overload of diagnostic_information is equivalent to:

if( p )
    try
        {
        rethrow_exception(p);
        }
    catch(...)
        {
        return current_exception_diagnostic_information();
        }
else return <unspecified-string-value>;

Notes:

  • The format of the returned string is unspecified.
  • The returned string is not user-friendly.
  • The returned string may include additional platform-specific diagnostic information.

Example:

this is a possible output from the diagnostic_information function, as used in libs/exception/example/example_io.cpp:

example_io.cpp(70): Throw in function class boost::shared_ptr<struct _iobuf> __cdecl my_fopen(const char *,const char *)
Dynamic exception type: class boost::exception_detail::clone_impl<struct fopen_error>
std::exception::what: example_io error
[struct boost::errinfo_api_function_ *] = fopen
[struct boost::errinfo_errno_ *] = 2, "No such file or directory"
[struct boost::errinfo_file_name_ *] = tmp1.txt
[struct boost::errinfo_file_open_mode_ *] = rb