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)

Execution support library (C++26)

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 (until C++17*) set_unexpected (until C++17*) Error numbers Error codes errno Assertions assert

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 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) Stacktrace stacktrace_entry (C++23) basic_stacktrace (C++23) Debugging support is_debugger_present (C++26) breakpoint_if_debugging (C++26) breakpoint (C++26)

 

std::basic_stacktrace

Member functions

basic_stacktrace::basic_stacktrace

basic_stacktrace::~basic_stacktrace

basic_stacktrace::operator=

basic_stacktrace::current

basic_stacktrace::get_allocator

Iterators

basic_stacktrace::beginbasic_stacktrace::cbegin

basic_stacktrace::endbasic_stacktrace::cend

basic_stacktrace::rbeginbasic_stacktrace::crbegin

basic_stacktrace::rendbasic_stacktrace::crend

Capacity

basic_stacktrace::empty

basic_stacktrace::size

basic_stacktrace::max_size

Element access

basic_stacktrace::operator[]

basic_stacktrace::at

Modifiers

basic_stacktrace::swap

Non-member functions

operator== operator<=>

swap(std::basic_stacktrace)

to_string(std::basic_stacktrace)

operator<<

Helper classes

hash<std::basic_stacktrace>

formatter<std::basic_stacktrace>

 

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)	creates a new basic_stacktrace (public member function)
(destructor) (C++23)	destroys the basic_stacktrace (public member function)
operator=	assigns to the basic_stacktrace (public member function)
current [static]	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	returns an iterator to the beginning (public member function)
endcend	returns an iterator to the end (public member function)
rbegincrbegin	returns a reverse iterator to the beginning (public member function)
rendcrend	returns a reverse iterator to the end (public member function)
Capacity
empty	checks whether the basic_stacktrace is empty (public member function)
size	returns the number of stacktrace entries (public member function)
max_size	returns the maximum possible number of stacktrace entries (public member function)
Element access
operator[]	access specified stacktrace entry (public member function)
at	access specified stacktrace entry with bounds checking (public member function)
Modifiers
swap	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)

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	Feature
__cpp_lib_stacktrace	202011L	(C++23)

Example

Run this code

import std;
using namespace std;
 
int func(int b) {
    stacktrace bs = stacktrace::current();
    cout << bs << endl;
    return b;
}
 
int main() {
#ifdef _DEBUG
    cout << "DEBUG:\n";
#else
    cout << "RELEASE\n";
#endif // DEBUG
 
    stacktrace bs = stacktrace::current();
    cout << bs << endl;
    cout << func(777);
}

Output:

RELEASE
0> F:\Source\Repos\Project1\main.cpp(17): Project1!main+0x36
1> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): Project1!__scrt_common_main_seh+0x10C
2> KERNEL32!BaseThreadInitThunk+0x1D
3> ntdll!RtlUserThreadStart+0x28
0> F:\Source\Repos\Project1\main.cpp(19): Project1!main+0x6F
1> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): Project1!__scrt_common_main_seh+0x10C
2> KERNEL32!BaseThreadInitThunk+0x1D
3> ntdll!RtlUserThreadStart+0x28
777
 
or
 
DEBUG:
0> F:\Source\Repos\Project1\main.cpp(17): Project1!main+0x76
1> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(79): Project1!invoke_main+0x39
2> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): Project1!__scrt_common_main_seh+0x12E
3> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(331): Project1!__scrt_common_main+0xE
4> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_main.cpp(17): Project1!mainCRTStartup+0xE
5> KERNEL32!BaseThreadInitThunk+0x1D
6> ntdll!RtlUserThreadStart+0x28
0> F:\Source\Repos\Project1\main.cpp(5): Project1!func+0x6D
1> F:\Source\Repos\Project1\main.cpp(19): Project1!main+0xAC
2> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(79): Project1!invoke_main+0x39
3> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(288): Project1!__scrt_common_main_seh+0x12E
4> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_common.inl(331): Project1!__scrt_common_main+0xE
5> D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_main.cpp(17): Project1!mainCRTStartup+0xE
6> KERNEL32!BaseThreadInitThunk+0x1D
7> ntdll!RtlUserThreadStart+0x28
777

See also

stacktrace_entry (C++23)

representation of an evaluation in a stacktrace (class)