Introduction: Patched libunwind from Android sources ( to build with standard NDK toolchain (android-15).
More: Author   ReportBugs   

-- mode: Outline --

This is version 1.0 of the unwind library. This library supports several architecture/operating-system combinations:

Linux/x86-64: Works well. Linux/x86: Works well. Linux/ARM: Works well. Linux/IA-64: Fully tested and supported. Linux/PARISC: Works well, but C library missing unwind-info. HP-UX/IA-64: Mostly works but known to have some serious limitations. Linux/AArch64: Newly added. Linux/PPC64: Newly added. Linux/SuperH: Newly added. FreeBSD/i386: Newly added. FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).

  • General Build Instructions

In general, this library can be built and installed with the following commands:

$ autoreconf -i # Needed only for building from git. Depends on libtool.
$ ./configure
$ make
$ make install prefix=PREFIX

where PREFIX is the installation prefix. By default, a prefix of /usr/local is used, such that libunwind.a is installed in /usr/local/lib and unwind.h is installed in /usr/local/include. For testing, you may want to use a prefix of /usr/local instead.

  • Building with Intel compiler

** Version 8 and later

Starting with version 8, the preferred name for the IA-64 Intel compiler is "icc" (same name as on x86). Thus, the configure-line should look like this:

$ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
  • Building on HP-UX

For the time being, libunwind must be built with GCC on HP-UX.

libunwind should be configured and installed on HP-UX like this:

$ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"

Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment.

** Workaround for older versions of GCC

GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The workaround is to issue the following commands before running "configure":

$ mkdir $top_dir/include/sys
$ cp /usr/include/sys/types.h $top_dir/include/sys

GCC v3.3.2 or later have been fixed and do not require this workaround.

  • Building for PowerPC64 / Linux

For building for power64 you should use:

$ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"

If your power support altivec registers: $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"

To check if your processor has support for vector registers (altivec): cat /proc/cpuinfo | grep altivec and should have something like this: cpu : PPC970, altivec supported

If libunwind seems to not work (backtracing failing), try to compile it with -O0, without optimizations. There are some compiler problems depending on the version of your gcc.

  • Building on FreeBSD

General building instructions apply. To build and execute several tests, you need libexecinfo library available in ports as devel/libexecinfo.

Development of the port was done of FreeBSD 8.0-STABLE. The library was build with the system compiler that is modified version of gcc 4.2.1, as well as the gcc 4.4.3.

  • Regression Testing

After building the library, you can run a set of regression tests with:

$ make check

** Expected results on IA-64 Linux

Unless you have a very recent C library and compiler installed, it is currently expected to have the following tests fail on IA-64 Linux:

Gtest-init        (should pass starting with glibc-2.3.x/gcc-3.4)
Ltest-init        (should pass starting with glibc-2.3.x/gcc-3.4)
test-ptrace        (should pass starting with glibc-2.3.x/gcc-3.4)
run-ia64-test-dyn1    (should pass starting with glibc-2.3.x)

This does not mean that libunwind cannot be used with older compilers or C libraries, it just means that for certain corner cases, unwinding will fail. Since they're corner cases, it is not likely for applications to trigger them.

Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's almost certainly a sign of an old assembler. The GNU assembler used to encode previous-stack-pointer-relative offsets incorrectly. This bug was fixed on 21-Sep-2004 so any later assembler will be fine.

** Expected results on x86 Linux

The following tests are expected to fail on x86 Linux:

Gtest-resume-sig    (fails to get SIGUSR2)
Ltest-resume-sig    (likewise)
Gtest-dyn1        (no dynamic unwind info support yet)
Ltest-dyn1        (no dynamic unwind info support yet)
test-setjmp        (longjmp() not implemented yet)
run-check-namespace    (no _Ux86_getcontext yet)

** Expected results on x86-64 Linux

The following tests are expected to fail on x86-64 Linux:

Gtest-dyn1        (no dynamic unwind info support yet)
Ltest-dyn1        (no dynamic unwind info support yet)
Gtest-init (see
Ltest-init        (likewise)
test-async-sig        (crashes due to bad unwind-info?)
test-setjmp        (longjmp() not implemented yet)
run-check-namespace    (no _Ux86_64_getcontext yet)
run-ptrace-mapper    (??? investigate)
run-ptrace-misc    (see

** Expected results on PARISC Linux

Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier versions of the compiler failed to generate the exception-handling program header (GNU_EH_FRAME) needed for unwinding.

The following tests are expected to fail on x86-64 Linux:

Gtest-bt   (backtrace truncated at kill() due to lack of unwind-info)
Ltest-bt   (likewise)
Gtest-resume-sig  (Gresume.c:my_rt_sigreturn() is wrong somehow)
Ltest-resume-sig  (likewise)
Gtest-init (likewise)
Ltest-init (likewise)
Gtest-dyn1 (no dynamic unwind info support yet)
Ltest-dyn1 (no dynamic unwind info support yet)
test-setjmp        (longjmp() not implemented yet)
run-check-namespace    (toolchain doesn't support HIDDEN yet)

** Expected results on HP-UX

"make check" is currently unsupported for HP-UX. You can try to run it, but most tests will fail (and some may fail to terminate). The only test programs that are known to work at this time are:


** Expected results on PPC64 Linux

"make check" should run with no more than 10 out of 24 tests failed.

  • Performance Testing

This distribution includes a few simple performance tests which give some idea of the basic cost of various libunwind operations. After building the library, you can run these tests with the following commands:

$ cd tests $ make perf

  • Contacting the Developers

Please direct all questions regarding this library to:

You can do this by sending a mail to with a body of:

subscribe libunwind-devel

or you can subscribe and manage your subscription via the web-interface at:
About Me
GitHub: Trinea
Facebook: Dev Tools