Namespaces anonymous_namespace{exception.cpp} Classes class exception_base_t class exception_t class logic_exception_t Typedefs typedef std::vector< std::string > stack_trace_t The stack trace results. More...
Functions static char const *LIBEXCEPT_LIBRARY_VERSION_STRING __attribute__ ((unused)) The library version as a string. More...
stack_trace_t collect_stack_trace (int stack_trace_depth) Collect the stack trace in a list of strings. More...
stack_trace_t collect_stack_trace_with_line_numbers (int stack_trace_depth) Collect the stack trace in a list of strings. More...
std::string demangle_cpp_name (char const *name) Demangle the specified type string. More...
void set_collect_stack (bool collect_stack) Set a general flag on whether to collect stack traces or not. More...
char const * version () Return a string to the version of the library when it was compiled. More...
int version_major () Return the major version number. More...
int version_minor () Return the minor version number. More...
int version_patch () Return the patch version number. More...
Variables constexpr int LIBEXCEPT_LIBRARY_VERSION_MAJOR = @LIBEXCEPT_VERSION_MAJOR@ constexpr int LIBEXCEPT_LIBRARY_VERSION_MINOR = @LIBEXCEPT_VERSION_MINOR@ constexpr int LIBEXCEPT_LIBRARY_VERSION_PATCH = @LIBEXCEPT_VERSION_PATCH@ constexpr int STACK_TRACE_DEPTH = 20 Default depth of stack traces collected. More...
Typedef Documentation

typedef std::vector< std::string > libexcept::exception_base_t::stack_trace_t

This typedef defines the type of the variables used to pass the stack trace between functions. It is a simple vector a C++ strings.

The first string (trace[0]) represents the current function. Note that the collected functions will include all the functions, including the exception_base_t::collect_stack_trace() and various calling functions from the libexcept library. In most cases this means 2 or 3 lines at the start of the stack trace vector are going to be about libexcept functions and not the function where the exception was raised.

Definition at line 60 of file exception.h.

Function Documentation

static char const* LIBEXCEPT_LIBRARY_VERSION_STRING libexcept::__attribute__ ( (unused) ) static

This variable represents the full library version at the time you compile your program.

Warning: This variable uses an attribute supported by the GNU C++ compiler which prevents Doxygen from finding this help block if declared in the .cpp file. This is why it is in the header.

See also: version()

stack_trace_t libexcept::collect_stack_trace ( int stack_trace_depth)

This function collects the current stack as a trace to log later.

By default, the stack trace shows you a number of backtrace equal to STACK_TRACE_DEPTH (which is 20 at time of writing). You may specify another number to get more or less lines. Note that a really large number will generally show you the entire stack since a number larger than the number of function pointers on the stack will return the entire stack.

If you pass 0 as stack_trace_depth then the function returns an empty vector of strings.

Passing std::numeric_limits<int>::max() as the stack_trace_depth parameter forces the function to return the entire stack trace available.

Note: This function is global so we can use it anywhere we'd like to get a stack trace and not just in exceptions. Very practical in C++ to get a stack trace directly in a vector of strings.; This function is not affected by the g_collect_stack flag. So you can always collect a stack trace. Only exceptions do not do so automatically if you set the g_collect_stack flag to false.

Attention: Use the collect_stack_with_line_numbers() to get demangled function names and line numbers. Note that this other function is considered very slow so do not use it in a standard exception. Consider using that other function only when debugging.

Parameters: [in]stack_trace_depthThe number of lines to capture in our stack trace.

Returns: The vector of strings with the stack trace.

See also: collect_stack_trace_with_line_numbers(); set_collect_stack()

Definition at line 248 of file exception.cpp.

Referenced by libexcept::exception_base_t::exception_base_t().

stack_trace_t libexcept::collect_stack_trace_with_line_numbers ( int stack_trace_depth)

This function collects the current stack as a trace including the line numbers and demangled function names as available.

The function also works like the collect_stack_trace() function.

Note: The function makes use of the addr2line and c++filt command line tools to convert the information. It is likely that if it fails it means your system does not have those two tools installed. Also, the addr2line requires the debug information in the libraries and executables. Without that information you will still get invalid answers in your stacktrace.

See also the libbacktrace library: https://gcc.gnu.org/viewcvs/gcc/trunk/libbacktrace/

Note: This function is not affected by the g_collect_stack flag. So you can always collect a stack trace. Only exceptions do not do so automatically if you set the g_collect_stack flag to false.

Todo:: I found a piece of code snippet on Catch2 which is used to demangle a C++ name. It is one simple ABI call! We would still need the translations of the IP address to a function name and line number, though.

#include "catch.hpp"
#include <cxxabi.h>
#include <typeinfo>
CATCH_TRANSLATE_EXCEPTION(std::exception& e) {
  std::string s;
  int status;
  const char* name = typeid(e).name();
  char* realname = abi::__cxa_demangle(name, 0, 0, &status);
  if(realname) {
    s.append(realname);
  } else {
    s.append(name);
  }
  s.append(": ");
  s.append(e.what());
  free(realname);
  return s;
}

Source: https://github.com/catchorg/Catch2/issues/539

Parameters: [in]stack_trace_depthThe number of lines to capture in our stack trace.

Returns: The vector of strings with the stack trace.

See also: collect_stack_trace(); set_collect_stack()

Definition at line 343 of file exception.cpp.

References demangle_cpp_name().

std::string libexcept::demangle_cpp_name ( char const * name)

C++ offers a typeid(\<type>).name() function, only that does not return a readable name in many cases. This function transforms that name back to the original. This is particularly useful for C++ base types. For example "unsigned short" becomes "t". To verify a type, it is quite practical.

This function demangles all names, including those we get when building a stack trace.

Parameters: [in]type_id_nameWhether to collect the stack or not.

Returns: The converted name.

See also: https://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-html-USERS-4.3/a01696.html

Definition at line 72 of file demangle.cpp.

Referenced by collect_stack_trace_with_line_numbers().

void libexcept::set_collect_stack ( bool collect_stack)

Because collecting the stack trace can be time consuming and once in a while you may need the highest possible speed including libexcept exceptions, we offer a flag to avoid all stack collection processing.

We especially use this feature when running tests because we generate the exceptions on purpose and do not want to get the stack trace which is rather useless in this case. We do not yet have any other situations where we do not want a stack trace.

By default collect_stack is already true so you do not need to change it on startup.

Warning: The function itself is not multithread safe. It is unlikely to cause any serious problems, though. Some threads may have or may be missing the stack trace, that's all. If you never call this function, all threads will always include the stack trace. Calling this function before you create threads will resolve all possible issues (if you do not have to dynamically change the flag.)

Parameters: [in]collect_stackWhether to collect the stack or not.

Definition at line 202 of file exception.cpp.

References libexcept::anonymous_namespace{exception.cpp}::g_collect_stack.

char const* libexcept::version ( )

This function returns the library version when it was compiled as a string. It can be used to compare against a version you support (i.e. the version your software was compiled against could be different.)

Returns: A constant string that represents the library version.

Definition at line 53 of file version.cpp.

int libexcept::version_major ( )

This function returns the library major version number when it was compiled as an integer. It can be used to compare against a version you support.

Returns: The library major version number when it was compiled.

Definition at line 65 of file version.cpp.

References LIBEXCEPT_LIBRARY_VERSION_MAJOR.

int libexcept::version_minor ( )

This function returns the library minor version number when it was compiled as an integer. It can be used to compare against a version you support.

Returns: The library minor version number when it was compiled.

Definition at line 77 of file version.cpp.

References LIBEXCEPT_LIBRARY_VERSION_MINOR.

int libexcept::version_patch ( )

This function returns the library patch version number when it was compiled as an integer. It can be used to compare against a version you support.

Returns: The library minor version number when it was compiled.

Definition at line 89 of file version.cpp.

References LIBEXCEPT_LIBRARY_VERSION_PATCH.

Variable Documentation

constexpr int libexcept::LIBEXCEPT_LIBRARY_VERSION_MAJOR = @LIBEXCEPT_VERSION_MAJOR@

Definition at line 41 of file version.h.in.

Referenced by version_major().

constexpr int libexcept::LIBEXCEPT_LIBRARY_VERSION_MINOR = @LIBEXCEPT_VERSION_MINOR@

Definition at line 42 of file version.h.in.

Referenced by version_minor().

constexpr int libexcept::LIBEXCEPT_LIBRARY_VERSION_PATCH = @LIBEXCEPT_VERSION_PATCH@

Definition at line 43 of file version.h.in.

Referenced by version_patch().

int libexcept::exception_base_t::STACK_TRACE_DEPTH = 20

This parameter defines the default number of lines returned by the collect_stack_trace() function.

All the functions that call the collect_stack_trace() have a stack_trace_depth parameter you can use to change this value.

Note that a value of 0 is valid as the stack trace depth. This just means not even one line is going to be taken from the stack.

Attention: It is to be noted that since a few functions from the libexcept are going to be included in your stack trace, using a very small depth such as 1 or 2 is not going to be helpful at all. You would only get data about the libexcept functions instead of the actual function that generated the error.

Definition at line 58 of file exception.h.

Snap! A C++ Open Source CMS

libexcept: libexcept Namespace Reference

Recent Posts

Recent blog posts