libunwind LLVM Unwinder
Overview
libunwind is an implementation of the interface defined by the HP libunwind project. It was contributed by Apple as a way to enable clang++ to port to platforms that do not have a system unwinder. It is intended to be a small and fast implementation of the ABI, leaving off some features of HP's libunwind that never materialized (e.g. remote unwinding).
The unwinder has two levels of API. The high level APIs are the _Unwind_* functions which implement functionality required by __cxa_* exception functions. The low level APIs are the unw_* functions which are an interface defined by the old HP libunwind project.
Getting Started with libunwind
Current Status
libunwind is a production-quality unwinder, with platform support for DWARF unwind info, SjLj, and ARM EHABI.
The low level libunwind API was designed to work either in-process (aka local) or to operate on another process (aka remote), but only the local path has been implemented. Remote unwinding remains as future work.
Platform and Compiler Support
libunwind is known to work on the following platforms:
| OS | Arch | Compilers | Unwind Info |
|---|---|---|---|
| Any | i386, x86_64, ARM | Clang | SjLj |
| Bare Metal | ARM | Clang, GCC | EHABI |
| FreeBSD | i386, x86_64, ARM64 | Clang | DWARF CFI |
| iOS | ARM | Clang | SjLj |
| Linux | ARM | Clang, GCC | EHABI |
| Linux | i386, x86_64, ARM64 | Clang, GCC | DWARF CFI |
| macOS | i386, x86_64 | Clang, GCC | DWARF CFI |
| NetBSD | x86_64 | Clang, GCC | DWARF CFI |
| Windows | i386, x86_64, ARM, ARM64 | Clang | DWARF CFI |
The following minimum compiler versions are strongly recommended.
- Clang 3.5 and above
- GCC 4.7 and above.
Anything older may work.
Notes and Known Issues
- TODO
Getting Involved
First please review our Developer's Policy and Getting started with LLVM.
Bug Reports
If you think you've found a bug in libunwind, please report it using the LLVM Bugzilla. If you're not sure, you can post a message to the cfe-dev mailing list or on IRC. Please include "libunwind" in your subject.
Patches
If you want to contribute a patch to libunwind, the best place for that is Phabricator. Please include [libunwind] in the subject and add cfe-commits as a subscriber. Also make sure you are subscribed to the cfe-commits mailing list.
Discussion and Questions
Send discussions and questions to the cfe-dev mailing list. Please include [libunwind] in the subject.