1# Android bionic status 2 3This document details libc/libm/libdl additions and behavior changes. 4 5See also 6[Android linker changes for NDK developers](../android-changes-for-ndk-developers.md) 7for changes related to native code loading in various Android releases. 8 9## Bionic function availability 10 11### POSIX 12 13You can see the current status with respect to POSIX in the form of tests: 14https://android.googlesource.com/platform/bionic/+/main/tests/headers/posix/ 15 16Some POSIX functionality is not supported by the Linux kernel, and 17is guarded with tests for `__linux__`. Other functionality is not 18supported by bionic or glibc, and guarded with tests for `__BIONIC__` 19and `__GLIBC__`. In other cases historical accidents mean 32-bit 20bionic diverged but 64-bit bionic matches POSIX; these are guarded with 21`__LP64__`. 22 23Most bionic-only diversions should be accompanied by an explanatory comment. 24 25Missing functions are either obsolete or explicitly disallowed by SELinux: 26 * `a64l`/`l64a` 27 * `confstr` 28 * `crypt`/`encrypt`/`setkey` 29 * `gethostid` 30 * `shm_open`/`shm_unlink` 31 * `sockatmark` 32 * `ualarm` 33 34Missing functionality: 35 * `<aio.h>` 36 * `<monetary.h>`. See 37 [discussion](https://github.com/android/ndk/issues/1182). 38 * `<wordexp.h>` 39 * Locales. Although bionic contains the various `_l()` functions, the only 40 locale supported is a UTF-8 C/POSIX locale. Most of the POSIX APIs are 41 insufficient to support the wide range of languages used by Android users, 42 and apps should use icu4c (or do their i18n work in Java) instead. 43 * Robust mutexes. See 44 [discussion](https://github.com/android/ndk/issues/1181). 45 * Thread cancellation (`pthread_cancel`). Unlikely to ever be implemented 46 because of the difficulty and cost of implementing it, and the difficulty 47 of using it correctly. See 48 [This is why we can't have safe cancellation points](https://lwn.net/Articles/683118/) 49 for more about thread cancellation. 50 51Run `./libc/tools/check-symbols-glibc.py` in bionic/ for the current 52list of POSIX functions implemented by glibc but not by bionic. 53 54### libc 55 56Current libc symbols: https://android.googlesource.com/platform/bionic/+/main/libc/libc.map.txt 57 58New libc functions in V (API level 35): 59 * New `android_crash_detail_register`, `android_crash_detail_unregister`, 60 `android_crash_detail_replace_name`, and `android_crash_detail_replace_data` 61 functionality for adding arbitrary data to tombstones 62 (see `<android/crash_detail.h>` for full documentation). 63 * `tcgetwinsize`, `tcsetwinsize`, `_Fork` (POSIX Issue 8 additions). 64 * `timespec_getres` (C23 addition). 65 * `localtime_rz`, `mktime_z`, `tzalloc`, and `tzfree` (NetBSD 66 extensions implemented in tzcode, and the "least non-standard" 67 functions for avoiding $TZ if you need to use multiple timezones in 68 multi-threaded C). 69 * `mbsrtowcs_l` and `wcsrtombs_l` aliases for `mbsrtowcs` and `wcsrtombs`. 70 * GNU extensions `strerrordesc_np` and `strerrorname_np`. 71 * New system call wrappers: `__riscv_flush_icache` (`<sys/cachectl.h>`), 72 `__riscv_hwprobe` (`<sys/hwprobe.h>`), `epoll_pwait2`/`epoll_pwait2_64` (`<sys/epoll.h>`). 73 74New libc behavior in V (API level 35): 75 * Added `LD_SHOW_AUXV` to the dynamic linker to dump the ELF auxiliary 76 vector if the environment variable is set. 77 * The printf family now supports `%#m` to print the name of the errno 78 constant (rather than the description printed by `%m`). 79 80New libc functions in U (API level 34): 81 * `close_range` and `copy_file_range` (Linux-specific GNU extensions). 82 * `memset_explicit` in <string.h> (C23 addition). 83 * `__freadahead` in <stdio_ext.h> (in musl but not glibc). 84 * `posix_spawn_file_actions_addchdir_np` and 85 `posix_spawn_file_actions_addfchdir_np` in <spawn.h> (in musl/glibc 86 and macOS, but not iOS). 87 88New libc behavior in U (API level 34): 89 * Support for `%b` and `%B` in the printf/wprintf family, `%b` in the 90 scanf/wscanf family, and `0b` prefixes with base 0 in the strtol/wcstol 91 family. 92 * Support for `wN` length modifiers in the printf/wprintf family. 93 * tmpfile() now respects $TMPDIR. 94 95New libc functions in T (API level 33): 96 * `backtrace`, `backtrace_symbols`, `backtrace_symbols_fd` (`<execinfo.h>`). 97 * New system call wrappers: `preadv2`, `preadv64v2`, `pwritev2`, 98 `pwritev64v2`. 99 100New libc functions in S (API level 31): 101 * New hooks for sanitizers for TLS access: `__libc_get_static_tls_bounds`, 102 `__libc_register_thread_exit_callback`, `__libc_iterate_dynamic_tls`, 103 `__libc_register_dynamic_tls_listeners`. 104 * New helper to allow the zygote to give each zygote child its own stack 105 cookie (currently unused): `android_reset_stack_guards`. 106 * Non-inline symbols for `ffsl`, `ffsll`. 107 * New system call wrappers: `pidfd_getfd`, `pidfd_open`, `pidfd_send_signal`, 108 `process_madvise`. 109 110New libc functions in R (API level 30): 111 * Full C11 `<threads.h>` (available as inlines for older API levels). 112 * `memfd_create` and `mlock2` (Linux-specific GNU extensions). 113 * `renameat2` and `statx` (Linux-specific GNU extensions). 114 * `pthread_cond_clockwait`/`pthread_mutex_clocklock`/`pthread_rwlock_clockrdlock`/`pthread_rwlock_clockwrlock`/`sem_clockwait` 115 116New libc behavior in R (API level 30): 117 * [fdsan](fdsan.md) now aborts when it detects common file descriptor errors, 118 rather than just logging. 119 120New libc functions in Q (API level 29): 121 * `timespec_get` (C11 `<time.h>` addition) 122 * `reallocarray` (BSD/GNU extension in `<malloc.h>` and `<stdlib.h>`) 123 * `res_randomid` (in `<resolv.h>`) 124 * `pthread_sigqueue` (GNU extension) 125 * `getloadavg` (BSD/GNU extension in <stdlib.h>) 126 127New libc behavior in Q (API level 29): 128 * Whole printf family now supports the GNU `%m` extension, rather than a 129 special-case hack in `syslog`. 130 * `popen` now always uses `O_CLOEXEC`, not just with the `e` extension. 131 * Bug fixes to handling of UTF-8 U+fffe/U+ffff and code points above U+10ffff. 132 * `aligned_alloc` correctly verifies that `size` is a multiple of `alignment`. 133 * Using `%n` with the printf family is now reported as a FORTIFY failure. 134 Previous versions of Android would ignore the `%n` but not consume the 135 corresponding pointer argument, leading to obscure errors. The scanf family 136 is unchanged. 137 * Support in strptime for `%F`, `%G`, `%g`, `%P`, `%u`, `%V`, and `%v`. 138 (strftime already supported them all.) 139 * [fdsan](fdsan.md) detects and logs common file descriptor errors at runtime. 140 141New libc functions in P (API level 28): 142 * `aligned_alloc` 143 * `__freading`/`__fwriting` (completing <stdio_ext.h>) 144 * `endhostent`/`endnetent`/`endprotoent`/`getnetent`/`getprotoent`/`sethostent`/`setnetent`/`setprotoent` (completing <netdb.h>) 145 * `fexecve` 146 * `fflush_unlocked`/`fgetc_unlocked`/`fgets_unlocked`/`fputc_unlocked`/`fputs_unlocked`/`fread_unlocked`/`fwrite_unlocked` 147 * `getentropy`/`getrandom` (adding <sys/random.h>) 148 * `getlogin_r` 149 * `glob`/`globfree` (adding <glob.h>) 150 * `hcreate`/`hcreate_r`/`hdestroy`/`hdestroy_r`/`hsearch`/`hsearch_r` (completing <search.h>) 151 * `iconv`/`iconv_close`/`iconv_open` (adding <iconv.h>) 152 * `pthread_attr_getinheritsched`/`pthread_attr_setinheritsched`/`pthread_setschedprio` 153 * `pthread_mutexattr_getprotocol`/`pthread_mutexattr_setprotocol` (mutex priority inheritance) 154 * <signal.h> support for `sigaction64_t` and `sigset64_t` allowing LP32 access to real-time signals 155 * <spawn.h> 156 * `swab` 157 * `syncfs` 158 159New libc behavior in P (API level 28): 160 * `%C` and `%S` support in the printf family (previously only the wprintf family supported these). 161 * `%mc`/`%ms`/`%m[` support in the scanf family. 162 * `%s` support in strptime (strftime already supported it). 163 * Using a `pthread_mutex_t` after it's been destroyed will be detected at 164 runtime and reported as a FORTIFY failure. 165 * Passing a null `FILE*` or `DIR*` to libc is now detected at runtime and 166 reported as a FORTIFY failure. 167 168New libc functions in O (API level 26): 169 * `sendto` FORTIFY support 170 * `__system_property_read_callback`/`__system_property_wait` 171 * legacy `bsd_signal` 172 * `catclose`/`catgets`/`catopen` (adding <nl_types.h>) 173 * `ctermid` 174 * all 6 <grp.h>/<pwd.h> (get|set|end)(gr|pw)ent functions 175 * `futimes`/`futimesat`/`lutimes` 176 * `getdomainname`/`setdomainname` 177 * `getsubopt` 178 * `hasmntopt` 179 * `mallopt` 180 * `mblen` 181 * 4 <sys/msg.h> `msg*` functions 182 * <langinfo.h> `nl_langinfo`/`nl_langinfo_l` 183 * `pthread_getname_np` 184 * 2 new Linux system calls `quotactl` and `sync_file_range` 185 * 4 <sys/sem.h> `sem*` functions 186 * 4 <sys/shm.h> `shm*` functions 187 * 5 legacy <signal.h> functions: `sighold`/`sigignore`/`sigpause`/`sigrelse`/`sigset` 188 * `strtod_l`/`strtof_l`/`strtol_l`/`strtoul_l` 189 * <wctype.h> `towctrans`/`towctrans_l`/`wctrans`/`wctrans_l` 190 191New libc behavior in O (API level 26): 192 * Passing an invalid `pthread_t` to libc is now detected at runtime and 193 reported as a FORTIFY failure. Most commonly this is a result of confusing 194 `pthread_t` and `pid_t`. 195 196New libc functions in N (API level 24): 197 * more FORTIFY support functions (`fread`/`fwrite`/`getcwd`/`pwrite`/`write`) 198 * all remaining `_FILE_OFFSET_BITS=64` functions, completing `_FILE_OFFSET_BITS=64` support in bionic (8) 199 * all 7 `pthread_barrier*` functions 200 * all 5 `pthread_spin*` functions 201 * `lockf`/`preadv`/`pwritev`/`scandirat` and `off64_t` variants 202 * `adjtimex`/`clock_adjtime` 203 * <ifaddrs.h> `getifaddrs`/`freeifaddrs`/`if_freenameindex`/`if_nameindex` 204 * `getgrgid_r`/`getgrnam_r` 205 * GNU extensions `fileno_unlocked`/`strchrnul` 206 * 32-bit `prlimit` 207 208New libc behavior in N (API level 24): 209 * `sem_wait` now returns EINTR when interrupted by a signal. 210 211New libc functions in M (API level 23): 212 * <dirent.h> `telldir`, `seekdir`. 213 * <malloc.h> `malloc_info`. 214 * <netdb.h> `gethostbyaddr_r`, `gethostbyname2_r`. 215 * <pthread.h> `pthread_rwlockattr_getkind_np`/`pthread_rwlockattr_setkind_np`. 216 * <pty.h> `forkpty`, `openpty`. 217 * <signal.h> `sigqueue`, `sigtimedwait`, `sigwaitinfo`. 218 * <stdio.h> `fmemopen`, `open_memstream`, `feof_unlocked`, `ferror_unlocked`, `clearerr_unlocked`. 219 * <stdio_ext.h> `__flbf`, `__freadable`, `__fsetlocking`, `__fwritable`, `__fbufsize`, `__fpending`, `_flushlbf`, `__fpurge`. 220 * <stdlib.h> `mkostemp`/`mkostemps`, `lcong48`. 221 * <string.h> `basename`, `strerror_l`, `strerror_r`, `mempcpy`. 222 * <sys/sysinfo.h> `get_nprocs_conf`/`get_nprocs`, `get_phys_pages`, `get_avphys_pages`. 223 * <sys/uio.h> `process_vm_readv`/`process_vm_writev`. 224 * `clock_getcpuclockid`, `login_tty`, `mkfifoat`, `posix_madvise`, `sethostname`, `strcasecmp_l`/`strncasecmp_l`. 225 * <wchar.h> `open_wmemstream`, `wcscasecmp_l`/`wcsncasecmp_l`, `wmempcpy`. 226 * all of <error.h>. 227 * re-introduced various <resolv.h> functions: `ns_format_ttl`, `ns_get16`, `ns_get32`, `ns_initparse`, `ns_makecanon`, `ns_msg_getflag`, `ns_name_compress`, `ns_name_ntol`, `ns_name_ntop`, `ns_name_pack`, `ns_name_pton`, `ns_name_rollback`, `ns_name_skip`, `ns_name_uncompress`, `ns_name_unpack`, `ns_parserr`, `ns_put16`, `ns_put32`, `ns_samename`, `ns_skiprr`, `ns_sprintrr`, and `ns_sprintrrf`. 228 229New libc functions in L (API level 21): 230 * <android/dlext.h>. 231 * <android/set_abort_message.h>. 232 * <arpa/inet.h> `inet_lnaof`, `inet_netof`, `inet_network`, `inet_makeaddr`. 233 * <wctype.h> `iswblank`. 234 * <ctype.h> `isalnum_l`, `isalpha_l`, `isblank_l`, `icntrl_l`, `isdigit_l`, `isgraph_l`, `islower_l`, `isprint_l`, `ispunct_l`, `isspace_l`, `isupper_l`, `isxdigit_l`, `_tolower`, `tolower_l`, `_toupper`, `toupper_l`. 235 * <fcntl.h> `fallocate`, `posix_fadvise`, `posix_fallocate`, `splice`, `tee`, `vmsplice`. 236 * <inttypes.h> `wcstoimax`, `wcstoumax`. 237 * <link.h> `dl_iterate_phdr`. 238 * <mntent.h> `setmntent`, `endmntent`, `getmntent_r`. 239 * <poll.h> `ppoll`. 240 * <pthread.h> `pthread_condattr_getclock`, `pthread_condattr_setclock`, `pthread_mutex_timedlock`, `pthread_gettid_np`. 241 * <sched.h> `setns`. 242 * <search.h> `insque`, `remque`, `lfind`, `lsearch`, `twalk`. 243 * <stdio.h> `dprintf`, `vdprintf`. 244 * <stdlib.h> `initstate`, `setstate`, `getprogname`/`setprogname`, `atof`/`strtof`, `at_quick_exit`/`_Exit`/`quick_exit`, `grantpt`, `mbtowc`/`wctomb`, `posix_openpt`, `rand_r`/`rand`/`random`/`srand`/`srandom`, `strtold_l`/`strtoll_l`/`strtoull_l`. 245 * <string.h> `strcoll_l`/`strxfrm_l`, `stpcpy`/`stpncpy`. 246 * <sys/resource.h> `prlimit`. 247 * <sys/socket.h> `accept4`, `sendmmsg`. 248 * <sys/stat.h> `mkfifo`/`mknodat`. 249 * <time.h> `strftime_l`. 250 * <unistd.h> `dup3`, `execvpe`, `getpagesize`, `linkat`/`symlinkat`/`readlinkat`, `truncate`. 251 * <wchar.h> `wcstof`, `vfwscanf`/`vswscanf`/`vwscanf`, `wcstold_l`/`wcstoll`/`wcstoll_l`/`wcstoull`/`wcstoull_l`, `mbsnrtowcs`/`wcsnrtombs`, `wcscoll_l`/`wcsxfrm_l`. 252 * <wctype.h> `iswalnum_l`/`iswalpha_l`/`iswblank_l`/`iswcntrl_l`/`iswctype_l`/`iswdigit_l`/`iswgraph_l`/`iswlower_l`/`iswprint_l`/`iswpunct_l`/`iswspace_l`/`iswupper_l`/`iswxdigit_l`, `wctype_l`, `towlower_l`/`towupper_l`. 253 * all of <fts.h>. 254 * all of <locale.h>. 255 * all of <sys/epoll.h>. 256 * all of <sys/fsuid.h>. 257 * all of <sys/inotify.h>. 258 * all of <uchar.h>. 259 260New libc functions in K (API level 19): 261 * <inttypes.h> `imaxabs`, `imaxdiv`. 262 * <stdlib.h> `abs`, `labs`, `llabs`. 263 * <sys/stat.h> `futimens`. 264 * all of <sys/statvfs.h>. 265 * all of <sys/swap.h>. 266 * all of <sys/timerfd.h>. 267 268New libc functions in J-MR2 (API level 18): 269 * <stdio.h> `getdelim` and `getline`. 270 * <sys/auxv.h> `getauxval`. 271 * <sys/signalfd.h> `signalfd`. 272 273New libc functions in J-MR1 (API level 17): 274 * <ftw.h>. 275 * <signal.h> `psiginfo` and `psignal`. 276 * `getsid`, `malloc_usable_size`, `mlockall`/`munlockall`, `posix_memalign`, `unshare`. 277 278New libc functions in J (API level 16): 279 * the <search.h> tree functions `tdelete`, `tdestroy`, `tfind`, and `tsearch`. 280 * `faccessat`, `readahead`, `tgkill`. 281 * all of <sys/xattr.h>. 282 283libc function count over time: 284 285| OS | API level | Function count | 286|-------|-----------|----------------| 287| J | 16 | 842 | 288| J MR1 | 17 | 870 | 289| J MR2 | 18 | 878 | 290| K | 19 | 893 | 291| L | 21 | 1118 | 292| M | 23 | 1183 | 293| N | 24 | 1228 | 294| O | 26 | 1280 | 295| P | 28 | 1378 | 296| Q | 29 | 1394 | 297 298Data collected by: 299``` 300ndk-r21$ for i in `ls -1v platforms/android-*/arch-arm/usr/lib/libc.so` ; do \ 301 echo $i; nm $i | grep -w T | wc -l ; done 302``` 303 304### libm 305 306Current libm symbols: https://android.googlesource.com/platform/bionic/+/main/libm/libm.map.txt 307 3080 remaining missing C11/POSIX libm functions. 309 310New libm functions in O (API level 26): 311 * <complex.h> `clog`/`clogf`, `cpow`/`cpowf` functions. 312 313New libm functions in M (API level 23): 314 * <complex.h> `cabs`, `carg`, `cimag`, `cacos`, `cacosh`, `casin`, `casinh`, `catan`, `catanh`, `ccos`, `ccosh`, `cexp`, `conj`, `cproj`, `csin`, `csinh`, `csqrt`, `ctan`, `ctanh`, `creal`, `cabsf`, `cargf`, `cimagf`, `cacosf`, `cacoshf`, `casinf`, `casinhf`, `catanf`, `catanhf`, `ccosf`, `ccoshf`, `cexpf`, `conjf`, `cprojf`, `csinf`, `csinhf`, `csqrtf`, `ctanf`, `ctanhf`, `crealf`, `cabsl`, `cprojl`, `csqrtl`. 315 * <math.h> `lgammal_r`. 316 317New libm functions in L (API level 21): 318 * <complex.h> `cabsl`, `cprojl`, `csqrtl`. 319 * <math.h> `isinf`, `significandl`. 320 321New libm functions in J-MR2 (API level 18): 322 * <math.h> `log2`, `log2f`. 323 324 325## Target API level behavioral differences 326 327Most bionic bug fixes and improvements have been made without checks for 328the app's `targetSdkVersion`. There are a handful of exceptions. (If in 329doubt, search the source for `android_get_application_target_sdk_version()`.) 330 331### Destroyed mutex checking (targetSdkVersion >= 28) 332 333If a destroyed `pthread_mutex_t` is passed to any of the mutex functions, apps 334targeting API level 28 or higher will see a 335"<function> called on a destroyed mutex" fortify failure. Apps targeting older 336API levels will just have the function fail with EBUSY (matching the likely 337behavior before we added the check). 338 339### Invalid `pthread_t` handling (targetSdkVersion >= 26) 340 341As part of a long-term goal to remove the global thread list, 342and in an attempt to flush out racy code, we changed how an invalid 343`pthread_t` is handled. For `pthread_detach`, `pthread_getcpuclockid`, 344`pthread_getschedparam`/`pthread_setschedparam`, `pthread_join`, and 345`pthread_kill`, instead of returning ESRCH when passed an invalid 346`pthread_t`, if you're targeting API level 26 or above, they'll abort with the 347message "attempt to use invalid pthread\_t". 348 349Note that this doesn't change behavior as much as you might think: the 350old lookup only held the global thread list lock for the duration of 351the lookup, so there was still a race between that and the dereference 352in the caller, given that callers actually need the tid to pass to some 353syscall or other, and sometimes update fields in the `pthread_internal_t` 354struct too. 355 356We can't check a thread's tid against 0 to see whether a `pthread_t` 357is still valid because a dead thread gets its thread struct unmapped 358along with its stack, so the dereference isn't safe. 359 360To fix your code, taking the affected functions one by one: 361 362 * `pthread_getcpuclockid` and `pthread_getschedparam`/`pthread_setschedparam` 363 should be fine. Unsafe calls to those seem highly unlikely. 364 365 * Unsafe `pthread_detach` callers probably want to switch to 366 `pthread_attr_setdetachstate` instead, or use 367 `pthread_detach(pthread_self());` from the new thread's start routine 368 rather than calling detach in the parent. 369 370 * `pthread_join` calls should be safe anyway, because a joinable thread 371 won't actually exit and unmap until it's joined. If you're joining an 372 unjoinable thread, the fix is to stop marking it detached. If you're 373 joining an already-joined thread, you need to rethink your design! 374 375 * Unsafe `pthread_kill` calls aren't portably fixable. (And are obviously 376 inherently non-portable as-is.) The best alternative on Android is to 377 use `pthread_gettid_np` at some point that you know the thread to be 378 alive, and then call `kill`/`tgkill` with signal 0 (which checks 379 whether a process exists rather than actually sending a 380 signal). That's still not completely safe because if you're too late 381 the tid may have been reused, but your code is inherently unsafe without 382 a redesign anyway. 383 384### Interruptable `sem_wait` (targetSdkVersion >= 24) 385 386POSIX says that `sem_wait` can be interrupted by delivery of a 387signal. This wasn't historically true in Android, and when we fixed this 388bug we found that existing code relied on the old behavior. To preserve 389compatibility, `sem_wait` can only return EINTR on Android if the app 390targets API level 24 or later. 391 392 393## FORTIFY 394 395The `_FORTIFY_SOURCE` macro can be used to enable extra 396automatic bounds checking for common libc functions. If a buffer 397overrun is detected, the program is safely aborted as in this 398[example](https://source.android.com/devices/tech/debug/native-crash#fortify). 399 400Note that Android's FORTIFY has been extended to cover other issues. It can 401detect, for example, passing `O_CREAT` to open(2) without specifying a mode. It 402also performs some checking regardless of whether the caller was built with 403FORTIFY enabled. From API level 28, for example, calling a `pthread_mutex_` 404function on a destroyed mutex, calling a `<dirent.h>` function on a null 405pointer, using `%n` with the printf(3) family, or using the scanf(3) `m` 406modifier incorrectly will all result in FORTIFY failures even for code not built 407with FORTIFY. 408 409More background information is available in our 410[FORTIFY in Android](https://android-developers.googleblog.com/2017/04/fortify-in-android.html) 411blog post, and there's more detail about the implementation in 412[The Anatomy of Clang FORTIFY](clang_fortify_anatomy.md). 413 414The Android platform is built with `-D_FORTIFY_SOURCE=2`. Users of ndk-build 415or the NDK's CMake toolchain file also get this by default with NDK r21 or 416newer. Users of other build systems 417need to manually enable FORTIFY by setting `_FORTIFY_SOURCE` themselves in 418whatever build system they're using. The exact subset of FORTIFY available to 419NDK users will depend on their target ABI level, because when a FORTIFY 420check can't be guaranteed at compile-time, a call to a run-time `_chk` 421function is added. 422