[thirdparty/gcc.git] / libbacktrace / README

The libbacktrace library
Initially written by Ian Lance Taylor <iant@golang.org>

The libbacktrace library may be linked into a program or library and
used to produce symbolic backtraces.
Sample uses would be to print a detailed backtrace when an error
occurs or to gather detailed profiling information.
In general the functions provided by this library are async-signal-safe,
meaning that they may be safely called from a signal handler.

The libbacktrace library is provided under a BSD license.
See the source files for the exact license text.

The public functions are declared and documented in the header file
backtrace.h, which should be #include'd by a user of the library.

Building libbacktrace will generate a file backtrace-supported.h,
which a user of the library may use to determine whether backtraces
will work.
See the source file backtrace-supported.h.in for the macros that it
defines.

As of October 2020, libbacktrace supports ELF, PE/COFF, Mach-O, and
XCOFF executables with DWARF debugging information.
In other words, it supports GNU/Linux, *BSD, macOS, Windows, and AIX.
The library is written to make it straightforward to add support for
other object file and debugging formats.

The library relies on the C++ unwind API defined at
https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html
This API is provided by GCC and clang.
Commit	Line	Data
eff02e4f	1	The libbacktrace library
f535f9d7	2	Initially written by Ian Lance Taylor <iant@golang.org>
eff02e4f ILT	3
eff02e4f ILT	4	The libbacktrace library may be linked into a program or library and
f535f9d7 ILT	5	used to produce symbolic backtraces.
	6	Sample uses would be to print a detailed backtrace when an error
	7	occurs or to gather detailed profiling information.
	8	In general the functions provided by this library are async-signal-safe,
	9	meaning that they may be safely called from a signal handler.
eff02e4f	10
f535f9d7 ILT	11	The libbacktrace library is provided under a BSD license.
f535f9d7 ILT	12	See the source files for the exact license text.
eff02e4f ILT	13
	14	The public functions are declared and documented in the header file
	15	backtrace.h, which should be #include'd by a user of the library.
	16
	17	Building libbacktrace will generate a file backtrace-supported.h,
	18	which a user of the library may use to determine whether backtraces
f535f9d7 ILT	19	will work.
	20	See the source file backtrace-supported.h.in for the macros that it
	21	defines.
eff02e4f	22
f535f9d7 ILT	23	As of October 2020, libbacktrace supports ELF, PE/COFF, Mach-O, and
	24	XCOFF executables with DWARF debugging information.
	25	In other words, it supports GNU/Linux, *BSD, macOS, Windows, and AIX.
	26	The library is written to make it straightforward to add support for
	27	other object file and debugging formats.
	28
	29	The library relies on the C++ unwind API defined at
	30	https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html
	31	This API is provided by GCC and clang.