docs/UnifiedHeadersMigration.md

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:

```bash
$ 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.

[bugtracker]: https://github.com/android-ndk/ndk/issues


New APIs
--------

```diff
+./aaudio/AAudio.h
+./android/hardware_buffer.h
+./android/hardware_buffer_jni.h
+./android/sharedmem.h
+./android/sync.h
+./GLES/egl.h
```

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
--------------

```diff
+./android/legacy_errno_inlines.h
+./android/legacy_fenv_inlines_arm.h
+./android/legacy_fenv_inlines_mips.h
+./android/legacy_signal_inlines.h
+./android/legacy_stdlib_inlines.h
+./android/legacy_sys_stat_inlines.h
+./android/legacy_sys_wait_inlines.h
+./android/legacy_termios_inlines.h
```

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
------------------

```diff
+linux/...
-linux/...
```

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.

```diff
+./android/set_abort_message.h
+./android/versioning.h
-./asm/a.out.h
+./asm/unistd-common.h
+./asm/unistd-eabi.h
+./asm/unistd-oabi.h
+./bits/auxvec.h
+./bits/elf_arm64.h
+./bits/elf_arm.h
+./bits/elf_mips.h
+./bits/elf_x86_64.h
+./bits/elf_x86.h
+./bits/fcntl.h
+./bits/getopt.h
+./bits/glibc-syscalls.h
+./bits/ioctl.h
+./bits/lockf.h
+./bits/mbstate_t.h
+./bits/posix_limits.h
+./bits/pthread_types.h
+./bits/sa_family_t.h
+./bits/seek_constants.h
+./bits/strcasecmp.h
+./bits/struct_file.h
+./bits/sysconf.h
+./bits/timespec.h
+./bits/wchar_limits.h
+./bits/wctype.h
+./cpio.h
+./drm/amdgpu_drm.h
+./drm/armada_drm.h
+./drm/drm_fourcc.h
+./drm/drm.h
+./drm/drm_mode.h
+./drm/drm_sarea.h
+./drm/etnaviv_drm.h
+./drm/exynos_drm.h
+./drm/i810_drm.h
+./drm/i915_drm.h
+./drm/mga_drm.h
+./drm/msm_drm.h
+./drm/nouveau_drm.h
+./drm/omap_drm.h
+./drm/qxl_drm.h
+./drm/r128_drm.h
+./drm/radeon_drm.h
+./drm/savage_drm.h
+./drm/sis_drm.h
+./drm/tegra_drm.h
+./drm/vc4_drm.h
+./drm/vgem_drm.h
+./drm/via_drm.h
+./drm/virtgpu_drm.h
+./drm/vmwgfx_drm.h
+./error.h
+./ifaddrs.h
+./langinfo.h
-./machine/elf_machdep.h
-./machine/endian.h
-./machine/exec.h
-./machine/ieee.h
-./machine/wchar_limits.h
+./misc/cxl.h
+./mtd/inftl-user.h
+./mtd/mtd-abi.h
+./mtd/mtd-user.h
+./mtd/nftl-user.h
+./mtd/ubi-user.h
-./net/ethertypes.h
-./net/if_ether.h
-./net/if_ieee1394.h
-./net/if_types.h
-./nsswitch.h
+./nl_types.h
-./pathconf.h
+./pty.h
+./rdma/cxgb3-abi.h
+./rdma/cxgb4-abi.h
+./rdma/hfi/hfi1_user.h
+./rdma/hns-abi.h
+./rdma/ib_user_cm.h
+./rdma/ib_user_mad.h
+./rdma/ib_user_sa.h
+./rdma/ib_user_verbs.h
+./rdma/mlx4-abi.h
+./rdma/mlx5-abi.h
+./rdma/mthca-abi.h
+./rdma/nes-abi.h
+./rdma/ocrdma-abi.h
+./rdma/qedr-abi.h
+./rdma/rdma_netlink.h
+./rdma/rdma_user_cm.h
+./rdma/rdma_user_rxe.h
+./rdma/vmw_pvrdma-abi.h
+./scsi/cxlflash_ioctl.h
+./scsi/fc/fc_els.h
+./scsi/fc/fc_fs.h
+./scsi/fc/fc_gs.h
+./scsi/fc/fc_ns.h
+./scsi/scsi_bsg_fc.h
+./scsi/scsi.h
+./scsi/scsi_ioctl.h
+./scsi/scsi_netlink_fc.h
+./scsi/scsi_netlink.h
+./scsi/scsi_proto.h
+./scsi/sg.h
-./sgtty.h
+./sound/asequencer.h
+./sound/asoc.h
+./sound/asound_fm.h
+./sound/asound.h
+./sound/compress_offload.h
+./sound/compress_params.h
+./sound/emu10k1.h
+./sound/firewire.h
+./sound/hdsp.h
+./sound/hdspm.h
+./sound/sb16_csp.h
+./sound/sfnt_info.h
+./sound/snd_sst_tokens.h
+./sound/tlv.h
+./sound/usb_stream.h
+./stdio_ext.h
+./syscall.h
-./sys/cdefs_elf.h
+./sysexits.h
+./sys/fcntl.h
-./sys/glibc-syscalls.h
-./sys/ioctl_compat.h
+./sys/quota.h
-./sys/socketcalls.h
-./sys/syslimits.h
+./sys/syslog.h
+./sys/_system_properties.h
-./sys/ttychars.h
-./sys/ttydev.h
+./sys/unistd.h
-./sys/utime.h
+./tar.h
-./thread_db.h
-./util.h
+./video/edid.h
+./video/sisfb.h
+./video/uvesafb.h
+./wait.h
+./xen/evtchn.h
+./xen/gntalloc.h
+./xen/gntdev.h
+./xen/privcmd.h
```