Docs4dev
Docs
cpp / latest / utility / basic_stacktrace.html

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} }\)x0 in the current thread of execution is a sequence \(\small{ ({x}_{0}, \dots, {x}_{n})}\)(x0, ..., xn) of evaluations such that, for \(\small{i \ge 0}\)i≥0, \(\small{ {x}_{i} }\)xi is within the function invocation \(\small{ {x}_{i+1} }\)xi+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 std::stacktrace_entry
const_reference const value_type&
reference value_type&
const_iterator implementation-defined const LegacyRandomAccessIterator type that models random_access_iterator
iterator const_iterator
reverse_iterator std::reverse_iterator<iterator>
reverse_const_iterator std::reverse_iterator<const_iterator>
difference_type implementation-defined signed integer type
size_type implementation-defined unsigned integer type
allocator_type Allocator

Member functions

creates a new basic_stacktrace
(public member function)
destroys the basic_stacktrace
(public member function)
assigns to the basic_stacktrace
(public member function)
[static]
obtains the current stacktrace or its given part
(public static member function)
returns the associated allocator
(public member function)
Iterators
returns an iterator to the beginning
(public member function)
returns an iterator to the end
(public member function)
returns a reverse iterator to the beginning
(public member function)
returns a reverse iterator to the end
(public member function)
Capacity
checks whether the basic_stacktrace is empty
(public member function)
returns the number of stacktrace entries
(public member function)
returns the maximum possible number of stacktrace entries
(public member function)
Element access
access specified stacktrace entry
(public member function)
access specified stacktrace entry with bounds checking
(public member function)
Modifiers
swaps the contents
(public member function)

Non-member functions

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

Helper classes

(C++23)
hash support for std::basic_stacktrace
(class template specialization)
(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 Feature
__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.

#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 (the lines ending with '⤶' arrows are split to fit the width):
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

(C++23)
representation of an evaluation in a stacktrace
(class)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/utility/basic_stacktrace