3 [![Build Status](https://travis-ci.org/libunwind/libunwind.svg?branch=master)](https://travis-ci.org/libunwind/libunwind)
5 This is version 1.3 of the unwind library. This library supports
6 several architecture/operating-system combinations:
8 Linux/x86-64: Works well.
10 Linux/ARM: Works well.
11 Linux/IA-64: Works well.
12 Linux/PARISC: Works well, but C library missing unwind-info.
13 HP-UX/IA-64: Mostly works but known to have some serious limitations.
15 Linux/AArch64: Works well.
16 Linux/PPC64: Newly added.
17 Linux/SuperH: Newly added.
18 FreeBSD/i386: Works well.
19 FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).
20 Linux/Tilegx: Newly added (64-bit mode only).
22 * General Build Instructions
24 In general, this library can be built and installed with the following
27 $ ./autogen.sh # Needed only for building from git. Depends on libtool.
30 $ make install prefix=PREFIX
32 where PREFIX is the installation prefix. By default, a prefix of
33 /usr/local is used, such that libunwind.a is installed in
34 /usr/local/lib and unwind.h is installed in /usr/local/include. For
35 testing, you may want to use a prefix of /usr/local instead.
38 * Building with Intel compiler
40 ** Version 8 and later
42 Starting with version 8, the preferred name for the IA-64 Intel
43 compiler is "icc" (same name as on x86). Thus, the configure-line
44 should look like this:
46 $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
47 LDFLAGS="-L$PWD/src/.libs"
52 For the time being, libunwind must be built with GCC on HP-UX.
54 libunwind should be configured and installed on HP-UX like this:
56 $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"
58 Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
61 ** Workaround for older versions of GCC
63 GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The
64 workaround is to issue the following commands before running
67 $ mkdir $top_dir/include/sys
68 $ cp /usr/include/sys/types.h $top_dir/include/sys
70 GCC v3.3.2 or later have been fixed and do not require this
73 * Building for PowerPC64 / Linux
75 For building for power64 you should use:
77 $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
79 If your power support altivec registers:
80 $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
82 To check if your processor has support for vector registers (altivec):
83 cat /proc/cpuinfo | grep altivec
84 and should have something like this:
85 cpu : PPC970, altivec supported
87 If libunwind seems to not work (backtracing failing), try to compile
88 it with -O0, without optimizations. There are some compiler problems
89 depending on the version of your gcc.
93 General building instructions apply. To build and execute several tests,
94 you need libexecinfo library available in ports as devel/libexecinfo.
96 Development of the port was done of FreeBSD 8.0-STABLE. The library
97 was build with the system compiler that is modified version of gcc 4.2.1,
98 as well as the gcc 4.4.3.
102 After building the library, you can run a set of regression tests with:
106 ** Expected results on IA-64 Linux
108 Unless you have a very recent C library and compiler installed, it is
109 currently expected to have the following tests fail on IA-64 Linux:
111 Gtest-init (should pass starting with glibc-2.3.x/gcc-3.4)
112 Ltest-init (should pass starting with glibc-2.3.x/gcc-3.4)
113 test-ptrace (should pass starting with glibc-2.3.x/gcc-3.4)
114 run-ia64-test-dyn1 (should pass starting with glibc-2.3.x)
116 This does not mean that libunwind cannot be used with older compilers
117 or C libraries, it just means that for certain corner cases, unwinding
118 will fail. Since they're corner cases, it is not likely for
119 applications to trigger them.
121 Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's
122 almost certainly a sign of an old assembler. The GNU assembler used
123 to encode previous-stack-pointer-relative offsets incorrectly.
124 This bug was fixed on 21-Sep-2004 so any later assembler will be
127 ** Expected results on x86 Linux
129 The following tests are expected to fail on x86 Linux:
133 ** Expected results on x86-64 Linux
135 The following tests are expected to fail on x86-64 Linux:
137 run-ptrace-misc (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748
138 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749)
140 ** Expected results on PARISC Linux
142 Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier
143 versions of the compiler failed to generate the exception-handling
144 program header (GNU_EH_FRAME) needed for unwinding.
146 The following tests are expected to fail on x86-64 Linux:
148 Gtest-bt (backtrace truncated at kill() due to lack of unwind-info)
150 Gtest-resume-sig (Gresume.c:my_rt_sigreturn() is wrong somehow)
151 Ltest-resume-sig (likewise)
152 Gtest-init (likewise)
153 Ltest-init (likewise)
154 Gtest-dyn1 (no dynamic unwind info support yet)
155 Ltest-dyn1 (no dynamic unwind info support yet)
156 test-setjmp (longjmp() not implemented yet)
157 run-check-namespace (toolchain doesn't support HIDDEN yet)
159 ** Expected results on HP-UX
161 "make check" is currently unsupported for HP-UX. You can try to run
162 it, but most tests will fail (and some may fail to terminate). The
163 only test programs that are known to work at this time are:
168 tests/test-static-link
171 tests/Gtest-resume-sig
172 tests/Ltest-resume-sig
174 ** Expected results on PPC64 Linux
176 "make check" should run with no more than 10 out of 24 tests failed.
179 * Performance Testing
181 This distribution includes a few simple performance tests which give
182 some idea of the basic cost of various libunwind operations. After
183 building the library, you can run these tests with the following
189 * Contacting the Developers
191 Please direct all questions regarding this library to:
193 libunwind-devel@nongnu.org
195 You can do this by sending a mail to libunwind-request@nongnu.org with
198 subscribe libunwind-devel
200 or you can subscribe and manage your subscription via the
203 https://savannah.nongnu.org/mail/?group=libunwind
205 Or interact at the gihub page:
207 https://github.com/libunwind/libunwind