std::basic_stacktrace

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Diagnostics library

Exception handling exception uncaught_exceptionuncaught_exceptions (until C++20*)(C++17) exception_ptr (C++11) make_exception_ptr (C++11) current_exception (C++11) rethrow_exception (C++11) nested_exception (C++11) throw_with_nested (C++11) rethrow_if_nested (C++11) Exception handling failures terminate terminate_handler get_terminate (C++11) set_terminate bad_exception unexpected (until C++17*) unexpected_handler (until C++17*) get_unexpected (C++11)(until C++17*)     set_unexpected (until C++17*) Error codes Error codes errno

Exception categories logic_error invalid_argument domain_error length_error out_of_range runtime_error range_error overflow_error underflow_error tx_exception (TM TS) System error support error_category (C++11) generic_category (C++11) system_category (C++11) error_condition (C++11) errc (C++11) error_code (C++11) system_error (C++11) Assertions assert Stacktrace stacktrace_entry (C++23) basic_stacktrace (C++23)

 

std::basic_stacktrace

Member functions

basic_stacktrace::basic_stacktrace (C++23)

basic_stacktrace::~basic_stacktrace (C++23)

basic_stacktrace::operator= (C++23)

basic_stacktrace::current (C++23)

basic_stacktrace::get_allocator (C++23)

Iterators

basic_stacktrace::beginbasic_stacktrace::cbegin (C++23)(C++23)

basic_stacktrace::endbasic_stacktrace::cend (C++23)(C++23)

basic_stacktrace::rbeginbasic_stacktrace::crbegin (C++23)(C++23)

basic_stacktrace::rendbasic_stacktrace::crend (C++23)(C++23)

Capacity

basic_stacktrace::empty (C++23)

basic_stacktrace::size (C++23)

basic_stacktrace::max_size (C++23)

Element access

basic_stacktrace::operator[] (C++23)

basic_stacktrace::at (C++23)

Modifiers

basic_stacktrace::swap (C++23)

Non-member functions

operator== operator<=> (C++23)(C++23)

std::swap (C++23)

std::to_string (C++23)

operator<< (C++23)

Helper classes

std::hash<std::basic_stacktrace> (C++23)

std::formatter<std::basic_stacktrace> (C++23)

 

Defined in header <stacktrace>
template< class Allocator > class basic_stacktrace;	(1)	(since C++23)
using stacktrace =     std::basic_stacktrace<std::allocator<std::stacktrace_entry>>;	(2)	(since C++23)
namespace pmr { using stacktrace =     std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_entry>>; }	(3)	(since C++23)

1) The basic_stacktrace class template represents a snapshot of the whole stacktrace or its given part. It satisfies the requirement of AllocatorAwareContainer, SequenceContainer, and ReversibleContainer, except that only move, assignment, swap, and operations for const-qualified sequence containers are supported, and the semantics of comparison functions are different from those required for a container.

2) Convenience type alias for the basic_stacktrace using the default std::allocator.

3) Convenience type alias for the basic_stacktrace using the polymorphic allocator.

The invocation sequence of the current evaluation \(\small{ {x}_{0} }\)x₀ in the current thread of execution is a sequence \(\small{ ({x}_{0}, \dots, {x}_{n})}\)(x₀, ..., x_n) of evaluations such that, for \(\small{i \ge 0}\)i≥0, \(\small{ {x}_{i} }\)x_i is within the function invocation \(\small{ {x}_{i+1} }\)x_i+1.

A stacktrace is an approximate representation of an invocation sequence and consists of stacktrace entries.

A stacktrace entry represents an evaluation in a stacktrace. It is represented by std::stacktrace_entry in the C++ standard library.

Template parameters

Allocator

-

An allocator that is used to acquire/release memory and to construct/destroy the elements in that memory. The type must meet the requirements of Allocator. The program is ill-formed if Allocator::value_type is not std::stacktrace_entry.

Member types

Member type	Definition
value_type (C++23)	std::stacktrace_entry
const_reference (C++23)	const value_type&
reference (C++23)	value_type&
const_iterator (C++23)	implementation-defined const LegacyRandomAccessIterator type that models random_access_iterator
iterator (C++23)	const_iterator
reverse_iterator (C++23)	std::reverse_iterator<iterator>
reverse_const_iterator (C++23)	std::reverse_iterator<const_iterator>
difference_type (C++23)	implementation-defined signed integer type
size_type (C++23)	implementation-defined unsigned integer type
allocator_type (C++23)	Allocator

Member functions

(constructor) (C++23)	creates a new basic_stacktrace (public member function)
(destructor) (C++23)	destroys the basic_stacktrace (public member function)
operator= (C++23)	assigns to the basic_stacktrace (public member function)
current [static] (C++23)	obtains the current stacktrace or its given part (public static member function)
get_allocator (C++23)	returns the associated allocator (public member function)
Iterators
begincbegin (C++23)	returns an iterator to the beginning (public member function)
endcend (C++23)	returns an iterator to the end (public member function)
rbegincrbegin (C++23)	returns a reverse iterator to the beginning (public member function)
rendcrend (C++23)	returns a reverse iterator to the end (public member function)
Capacity
empty (C++23)	checks whether the basic_stacktrace is empty (public member function)
size (C++23)	returns the number of stacktrace entries (public member function)
max_size (C++23)	returns the maximum possible number of stacktrace entries (public member function)
Element access
operator[] (C++23)	access specified stacktrace entry (public member function)
at (C++23)	access specified stacktrace entry with bounds checking (public member function)
Modifiers
swap (C++23)	swaps the contents (public member function)

Non-member functions

operator==operator<=> (C++23)	compares the sizes and the contents of two basic_stacktrace values (function template)
std::swap(std::basic_stacktrace) (C++23)	specializes the std::swap algorithm (function template)
to_string (C++23)	returns a string with a description of the basic_stacktrace (function template)
operator<< (C++23)	performs stream output of basic_stracktrace (function template)

Helper classes

std::hash<std::basic_stacktrace> (C++23)	hash support for std::basic_stacktrace (class template specialization)
std::formatter<std::basic_stacktrace> (C++23)	formatting support for basic_stacktrace (class template specialization)

Notes

Support for custom allocators is provided for using basic_stacktrace on a hot path or in embedded environments. Users can allocate stacktrace_entry objects on the stack or in some other place, where appropriate.

The sequence of std::stacktrace_entry objects owned by a std::basic_stacktrace is immutable, and either is empty or represents a contiguous interval of the whole stacktrace.

boost::stacktrace::basic_stacktrace (available in Boost.Stacktrace) can be used instead when std::basic_stacktrace is not available.

Feature-test macro	Value	Std	Comment
__cpp_lib_stacktrace	202011L	(C++23)	Stacktrace library
__cpp_lib_formatters	202302L	(C++23)	Formatting std::thread::id and std::stacktrace

Example

The output obtained using Compiler Explorer: msvc and gcc.

Run this code

#include <iostream>
#include <stacktrace>
 
int nested_func(int c)
{
    std::cout << std::stacktrace::current() << '\n';
    return c + 1;
}
 
int func(int b)
{
    return nested_func(b + 1);
}
 
int main()
{
    std::cout << func(777);
}

Possible output:

msvc output:
0> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
1> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
2> C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-explorer-compiler20221122-31624-2ja1sf.8ytzw\example.cpp(15): output_s!main+0xE
3> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): output_s!__scrt_common_main_seh+0x10C
4> KERNEL32!BaseThreadInitThunk+0x14
5> ntdll!RtlUserThreadStart+0x21
779
 
gcc output:
   0# nested_func(int) at /app/example.cpp:7
   1# func(int) at /app/example.cpp:13
   2#      at /app/example.cpp:18
   3#      at :0
   4#      at :0
   5# 
 
779

See also

stacktrace_entry (C++23)

representation of an evaluation in a stacktrace (class)