1# libunwind 2 3[](https://travis-ci.org/libunwind/libunwind) 4 5This library supports several architecture/operating-system combinations: 6 7| System | Architecture | Status | 8| :------ | :----------- | :----- | 9| Linux | x86-64 | ✓ | 10| Linux | x86 | ✓ | 11| Linux | ARM | ✓ | 12| Linux | AArch64 | ✓ | 13| Linux | PPC32 | ✓ | 14| Linux | PPC64 | ✓ | 15| Linux | SuperH | ✓ | 16| Linux | IA-64 | ✓ | 17| Linux | PARISC | Works well, but C library missing unwind-info | 18| Linux | Tilegx | 64-bit mode only | 19| Linux | MIPS | Newly added | 20| Linux | RISC-V | 64-bit only | 21| HP-UX | IA-64 | Mostly works, but known to have serious limitations | 22| FreeBSD | x86-64 | ✓ | 23| FreeBSD | x86 | ✓ | 24| FreeBSD | AArch64 | ✓ | 25| Solaris | x86-64 | ✓ | 26 27## Libc Requirements 28 29libunwind depends on getcontext(), setcontext() functions which are missing 30from C libraries like musl-libc because they are considered to be "obsolescent" 31API by POSIX document. The following table tries to track current status of 32such dependencies 33 34 - r, requires 35 - p, provides its own implementation 36 - empty, no requirement 37 38| Architecture | getcontext | setcontext | 39|--------------|------------|------------| 40| aarch64 | p | | 41| arm | p | | 42| hppa | p | p | 43| ia64 | p | r | 44| mips | p | | 45| ppc32 | r | | 46| ppc64 | r | r | 47| riscv | p | p | 48| s390x | p | p | 49| sh | r | | 50| tilegx | r | r | 51| x86 | p | r | 52| x86_64 | p | p | 53 54## General Build Instructions 55 56In general, this library can be built and installed with the following 57commands: 58 59 $ autoreconf -i # Needed only for building from git. Depends on libtool. 60 $ ./configure --prefix=PREFIX 61 $ make 62 $ make install 63 64where `PREFIX` is the installation prefix. By default, a prefix of 65`/usr/local` is used, such that `libunwind.a` is installed in 66`/usr/local/lib` and `unwind.h` is installed in `/usr/local/include`. For 67testing, you may want to use a prefix of `/usr/local` instead. 68 69 70### Building with Intel compiler 71 72#### Version 8 and later 73 74Starting with version 8, the preferred name for the IA-64 Intel 75compiler is `icc` (same name as on x86). Thus, the configure-line 76should look like this: 77 78 $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \ 79 LDFLAGS="-L$PWD/src/.libs" 80 81 82### Building on HP-UX 83 84For the time being, libunwind must be built with GCC on HP-UX. 85 86libunwind should be configured and installed on HP-UX like this: 87 88 $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64" 89 90Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment. 91 92### Workaround for older versions of GCC 93 94GCC v3.0 and GCC v3.2 ship with a bad version of `sys/types.h`. The 95workaround is to issue the following commands before running 96`configure`: 97 98 $ mkdir $top_dir/include/sys 99 $ cp /usr/include/sys/types.h $top_dir/include/sys 100 101GCC v3.3.2 or later have been fixed and do not require this 102workaround. 103 104### Building for PowerPC64 / Linux 105 106For building for power64 you should use: 107 108 $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64" 109 110If your power support altivec registers: 111 112 $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec" 113 114To check if your processor has support for vector registers (altivec): 115 116 cat /proc/cpuinfo | grep altivec 117 118and should have something like this: 119 120 cpu : PPC970, altivec supported 121 122If libunwind seems to not work (backtracing failing), try to compile 123it with `-O0`, without optimizations. There are some compiler problems 124depending on the version of your gcc. 125 126### Building on FreeBSD 127 128General building instructions apply. To build and execute several tests 129on older versions of FreeBSD, you need libexecinfo library available in 130ports as devel/libexecinfo. This port has been removed as of 2017 and is 131indeed no longer needed. 132 133## Regression Testing 134 135After building the library, you can run a set of regression tests with: 136 137 $ make check 138 139### Expected results on IA-64 Linux 140 141Unless you have a very recent C library and compiler installed, it is 142currently expected to have the following tests fail on IA-64 Linux: 143 144* `Gtest-init` (should pass starting with glibc-2.3.x/gcc-3.4) 145* `Ltest-init` (should pass starting with glibc-2.3.x/gcc-3.4) 146* `test-ptrace` (should pass starting with glibc-2.3.x/gcc-3.4) 147* `run-ia64-test-dyn1` (should pass starting with glibc-2.3.x) 148 149This does not mean that libunwind cannot be used with older compilers 150or C libraries, it just means that for certain corner cases, unwinding 151will fail. Since they're corner cases, it is not likely for 152applications to trigger them. 153 154Note: If you get lots of errors in `Gia64-test-nat` and `Lia64-test-nat`, it's 155almost certainly a sign of an old assembler. The GNU assembler used 156to encode previous-stack-pointer-relative offsets incorrectly. 157This bug was fixed on 21-Sep-2004 so any later assembler will be 158fine. 159 160### Expected results on x86 Linux 161 162The following tests are expected to fail on x86 Linux: 163 164* `test-ptrace` 165 166### Expected results on x86-64 Linux 167 168The following tests are expected to fail on x86-64 Linux: 169 170* `run-ptrace-misc` (see <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748> 171 and <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749>) 172 173### Expected results on PARISC Linux 174 175Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier 176versions of the compiler failed to generate the exception-handling 177program header (`GNU_EH_FRAME`) needed for unwinding. 178 179The following tests are expected to fail on x86-64 Linux: 180 181* `Gtest-bt` (backtrace truncated at `kill()` due to lack of unwind-info) 182* `Ltest-bt` (likewise) 183* `Gtest-resume-sig` (`Gresume.c:my_rt_sigreturn()` is wrong somehow) 184* `Ltest-resume-sig` (likewise) 185* `Gtest-init` (likewise) 186* `Ltest-init` (likewise) 187* `Gtest-dyn1` (no dynamic unwind info support yet) 188* `Ltest-dyn1` (no dynamic unwind info support yet) 189* `test-setjmp` (`longjmp()` not implemented yet) 190* `run-check-namespace` (toolchain doesn't support `HIDDEN` yet) 191 192### Expected results on HP-UX 193 194`make check` is currently unsupported for HP-UX. You can try to run 195it, but most tests will fail (and some may fail to terminate). The 196only test programs that are known to work at this time are: 197 198* `tests/bt` 199* `tests/Gperf-simple` 200* `tests/test-proc-info` 201* `tests/test-static-link` 202* `tests/Gtest-init` 203* `tests/Ltest-init` 204* `tests/Gtest-resume-sig` 205* `tests/Ltest-resume-sig` 206 207### Expected results on PPC64 Linux 208 209`make check` should run with no more than 10 out of 24 tests failed. 210 211### Expected results on Solaris x86-64 212 213`make check` is passing 27 out of 33 tests. The following six tests are consistently 214failing: 215 216* `Gtest-concurrent` 217* `Ltest-concurrent` 218* `Ltest-init-local-signal` 219* `Lrs-race` 220* `test-setjmp` 221* `x64-unwind-badjmp-signal-frame` 222 223## Performance Testing 224 225This distribution includes a few simple performance tests which give 226some idea of the basic cost of various libunwind operations. After 227building the library, you can run these tests with the following 228commands: 229 230 $ cd tests 231 $ make perf 232 233## Contacting the Developers 234 235Please direct all questions regarding this library to <libunwind-devel@nongnu.org>. 236 237You can do this by sending an email to <libunwind-request@nongnu.org> with 238a body of "subscribe libunwind-devel", or you can subscribe and manage your 239subscription via the web-interface at <https://savannah.nongnu.org/mail/?group=libunwind>. 240 241You can also interact on our GitHub page: <https://github.com/libunwind/libunwind>. 242
){kind=link}