Unified Headers Migration Notes

When moving to unified headers, you may notice some differences. The unified headers represent nearly ten years of progress in the bionic header files, and in that time there have been a large number of cleanups (largely done for the sake of better compile times or better compatibility with other C libraries).

To get an idea of what has changed, we can generate a standalone toolchain using both the unified headers and the deprecated headers, and then diff the list of files in sysroot/usr/include.

List generated with:

$ android-ndk-r15/build/tools/make_standalone_toolchain.py \
    --arch arm --api 26 --install-dir unified-toolchain
$ android-ndk-r15/build/tools/make_standalone_toolchain.py \
    --arch arm --api 26 --deprecated-headers --install-dir deprecated-toolchain
$ (cd unified-toolchain/sysroot/usr/include/ && find . -type f) | \
    grep -v 'linux-android' | sort > unified-include
$ (cd deprecated-toolchain/sysroot/usr/include/ && find . -type f) | \
    sort > arm-26-include
$ diff -u0 arm-26-include unified-include | grep -vP '^@@'

The list below has been reorganized to group logical changes together for explanation.

The same steps can be repeated with your target architecure or API level to get information tailored for your application.

Note that the diff of the file contents themselves will be very large. Anything in the linux/ directory will be very difficult to read, as those files contain an “AUTOGENERATED” warning every five lines. Those headers are the Linux UAPI headers, so they shouldn't contain any surprises.

If your build is failing because a header has disappeared, use grep to search for the functions you‘re missing; they’ve likely only moved. If anything is actually missing, that may have been intentional, but could be an oversight. Search our bugtracker for both the name of the header and the functions you need. If you don‘t find anything (make sure you’re searching all bugs, not just open ones), file a bug. It may be intentional, but the bug serves as documentation either way.

One such header that was intentionally removed is <sys/atomics.h>. This was already not available for newer API levels when using the deprecated headers, but with unified headers it is not available for any API level. The NDK has support for C11 <stdatomic.h>, so you should migrate to that.

New APIs


The headers for these APIs will exist regardless of your target API level so you can access constants, prototypes, or types when conditionally accessing the API behind version checks with dlsym.

Legacy Support


Many functions in older bionic headers were provided as inline functions. This is not standards compliant, so this has been fixed in later releases. These headers provide those inlines if you're targeting an older release.

Linux UAPI Headers


These are all changes in the Linux UAPI headers. These are the headers provided by the Linux kernel as a backward compatible kernel API. Any changes here are due to changes upstream.

Everything Else

The rest of the list is just the usual additions and cleanups to libc headers. Many headers were added, some were removed. Headers that were removed were typically removed because they were unique to Android, and we moved the contents to match other C libraries.