Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::basic_stacktrace(3)      C++ Standard Libary     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::stack-
       trace_entry>>;

	}

	  1)  The basic_stacktrace class template represents a snapshot	of the
       whole stacktrace
	  or its given part. It	satisfies the requirement  of  AllocatorAware-
       Container,
	  SequenceContainer,  and  ReversibleContainer,	except that only move,
       assignment, swap,
	  and operations for  const-qualified  sequence	 containers  are  sup-
       ported, 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	 poly-
       morphic 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}\)i0,
	  \(\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  se-
       quence 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  LegacyRandomAc-
       cessIterator 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 en-
       tries
			(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   ba-
       sic_stracktrace
	  (C++23)			   (function template)

Helper classes
	  std::hash<std::basic_stacktrace>	  hash	support	 for  std::ba-
       sic_stacktrace
	  (C++23)				 (class	 template  specializa-
       tion)
	  std::formatter<std::basic_stacktrace>	 formatting  support  for  ba-
       sic_stacktrace
	  (C++23)				 (class	 template  specializa-
       tion)

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

	  The  sequence	 of  std::stacktrace_entry objects owned by a std::ba-
       sic_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-ex-
       plorer-compiler20221122-
	31624-2ja1sf.8ytzw\example.cpp(6): output_s!nested_func+0x1F
	1>     C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-ex-
       plorer-compiler20221122-
	31624-2ja1sf.8ytzw\example.cpp(12): output_s!func+0x15
	2>     C:\Users\ContainerAdministrator\AppData\Local\Temp\compiler-ex-
       plorer-compiler20221122-
	31624-2ja1sf.8ytzw\example.cpp(15): output_s!main+0xE
	3>	 D:\a\_work\1\s\src\vctools\crt\vcstartup\src\startup\exe_com-
       mon.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)

http://cppreference.com		  2024.06.10	      std::basic_stacktrace(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::basic_stacktrace&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help