# std::basic_stacktrace

> C++ Atlas: `cppatlas.com/w/cpp/utility/basic_stacktrace` | Source: https://en.cppreference.com/w/cpp/utility/basic_stacktrace | Domain: Utility | Standards: C++23

The invocation sequence of the current evaluation x0 in the current thread of execution is a sequence (x0, ..., xn) of evaluations such that, for i≥0, xi is within the function invocation xi+1.

## Official Specification Summary (cppreference)

```cpp
// 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 x₀ in the current thread of execution is a sequence (x₀,..., xn) of evaluations such that, for i≥0, xi is within the function invocation 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

- (constructor): creates a new `basic_stacktrace` (public member function)
- (destructor): 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`: returns the associated allocator (public member function)

**Iterators**

- `begin`, `cbegin`: returns an iterator to the beginning (public member function)
- `end`, `cend`: returns an iterator to the end (public member function)
- `rbegin`, `crbegin`: returns a reverse iterator to the beginning (public member function)
- `rend`, `crend`: 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==` (C++23), `operator<=>`: 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 | 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.

```cpp
#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:

```text
// 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

- [`stacktrace_entry`](https://en.cppreference.com/w/cpp/utility/stacktrace_entry) (C++23): representation of an evaluation in a stacktrace (class)

---
Attribution: content from https://en.cppreference.com/w/cpp/utility/basic_stacktrace (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.