std::basic_stacktrace(3)

NAME
std::basic_stacktrace - std::basic_stacktrace

Synopsis
 Defined in header <stacktrace>
 template< class Allocator > (1) (since
 class basic_stacktrace; C++23)
 using stacktrace = (2) (since
     std::basic_stacktrace<std::allocator<std::stacktrace_entry>>; C++23)
 namespace pmr {
 using stacktrace = (since
                        (3) C++23)
 std::basic_stacktrace<std::pmr::polymorphic_allocator<std::stacktrace_entry>>;
 }
   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[0] in the
   current thread of execution is a sequence \(\small{ ({x}_{0}, \dots,
   {x}_{n})}\)(x[0], ..., 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
               An allocator that is used to acquire/release memory and to
   Allocator - 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 obtains the current stacktrace or its given part
   [static] (public static member function)
   get_allocator returns the associated allocator
                 (public member function)

Iterators
   begin returns an iterator to the beginning
   cbegin (public member function)
   end returns an iterator to the end
   cend (public member function)
   rbegin returns a reverse iterator to the beginning
   crbegin (public member function)
   rend returns a reverse iterator to the end
   crend (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== compares the sizes and the contents of two
   operator<=> basic_stacktrace values
   (C++23) (function template)
   std::swap(std::basic_stacktrace) specializes the std::swap algorithm
   (C++23) (function template)
   to_string returns a string with a description of the
   (C++23) basic_stacktrace
                        (function template)
   operator<< performs stream output of basic_stracktrace
   (C++23) (function template)

Helper classes
   std::hash<std::basic_stacktrace> hash support for std::basic_stacktrace
   (C++23) (class template specialization)
   std::formatter<std::basic_stacktrace> formatting support for basic_stacktrace
   (C++23) (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. // 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 (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 representation of an evaluation in a stacktrace
   (C++23) (class)