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/+/master/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/+/master/libc/libc.map.txt 57 58New libc functions in U (API level 34): 59 * `close_range` and `copy_file_range` (Linux-specific GNU extensions). 60 * `memset_explicit` in <string.h> (C23 addition). 61 * `__freadahead` in <stdio_ext.h> (in musl but not glibc). 62 * `posix_spawn_file_actions_addchdir_np` and 63 `posix_spawn_file_actions_addfchdir_np` in <spawn.h> (in musl/glibc 64 and macOS, but not iOS). 65 66New libc behavior in U (API level 34): 67 * Support for `%b` and `%B` in the printf/wprintf family, `%b` in the 68 scanf/wscanf family, and `0b` prefixes with base 0 in the strtol/wcstol 69 family. 70 * Support for `wN` length modifiers in the printf/wprintf family. 71 * tmpfile() now respects $TMPDIR. 72 73New libc functions in T (API level 33): 74 * `backtrace`, `backtrace_symbols`, `backtrace_symbols_fd` (`<execinfo.h>`). 75 * New system call wrappers: `preadv2`, `preadv64v2`, `pwritev2`, 76 `pwritev64v2`. 77 78New libc functions in S (API level 31): 79 * New hooks for sanitizers for TLS access: `__libc_get_static_tls_bounds`, 80 `__libc_register_thread_exit_callback`, `__libc_iterate_dynamic_tls`, 81 `__libc_register_dynamic_tls_listeners`. 82 * New helper to allow the zygote to give each zygote child its own stack 83 cookie (currently unused): `android_reset_stack_guards`. 84 * Non-inline symbols for `ffsl`, `ffsll`. 85 * New system call wrappers: `pidfd_getfd`, `pidfd_open`, `pidfd_send_signal`, 86 `process_madvise`. 87 88New libc functions in R (API level 30): 89 * Full C11 `<threads.h>` (available as inlines for older API levels). 90 * `memfd_create` and `mlock2` (Linux-specific GNU extensions). 91 * `renameat2` and `statx` (Linux-specific GNU extensions). 92 * `pthread_cond_clockwait`/`pthread_mutex_clocklock`/`pthread_rwlock_clockrdlock`/`pthread_rwlock_clockwrlock`/`sem_clockwait` 93 94New libc behavior in R (API level 30): 95 * [fdsan](fdsan.md) now aborts when it detects common file descriptor errors, 96 rather than just logging. 97 98New libc functions in Q (API level 29): 99 * `timespec_get` (C11 `<time.h>` addition) 100 * `reallocarray` (BSD/GNU extension in `<malloc.h>` and `<stdlib.h>`) 101 * `res_randomid` (in `<resolv.h>`) 102 * `pthread_sigqueue` (GNU extension) 103 * `getloadavg` (BSD/GNU extension in <stdlib.h>) 104 105New libc behavior in Q (API level 29): 106 * Whole printf family now supports the GNU `%m` extension, rather than a 107 special-case hack in `syslog`. 108 * `popen` now always uses `O_CLOEXEC`, not just with the `e` extension. 109 * Bug fixes to handling of UTF-8 U+fffe/U+ffff and code points above U+10ffff. 110 * `aligned_alloc` correctly verifies that `size` is a multiple of `alignment`. 111 * Using `%n` with the printf family is now reported as a FORTIFY failure. 112 Previous versions of Android would ignore the `%n` but not consume the 113 corresponding pointer argument, leading to obscure errors. The scanf family 114 is unchanged. 115 * Support in strptime for `%F`, `%G`, `%g`, `%P`, `%u`, `%V`, and `%v`. 116 (strftime already supported them all.) 117 * [fdsan](fdsan.md) detects and logs common file descriptor errors at runtime. 118 119New libc functions in P (API level 28): 120 * `aligned_alloc` 121 * `__freading`/`__fwriting` (completing <stdio_ext.h>) 122 * `endhostent`/`endnetent`/`endprotoent`/`getnetent`/`getprotoent`/`sethostent`/`setnetent`/`setprotoent` (completing <netdb.h>) 123 * `fexecve` 124 * `fflush_unlocked`/`fgetc_unlocked`/`fgets_unlocked`/`fputc_unlocked`/`fputs_unlocked`/`fread_unlocked`/`fwrite_unlocked` 125 * `getentropy`/`getrandom` (adding <sys/random.h>) 126 * `getlogin_r` 127 * `glob`/`globfree` (adding <glob.h>) 128 * `hcreate`/`hcreate_r`/`hdestroy`/`hdestroy_r`/`hsearch`/`hsearch_r` (completing <search.h>) 129 * `iconv`/`iconv_close`/`iconv_open` (adding <iconv.h>) 130 * `pthread_attr_getinheritsched`/`pthread_attr_setinheritsched`/`pthread_setschedprio` 131 * `pthread_mutexattr_getprotocol`/`pthread_mutexattr_setprotocol` (mutex priority inheritance) 132 * <signal.h> support for `sigaction64_t` and `sigset64_t` allowing LP32 access to real-time signals 133 * <spawn.h> 134 * `swab` 135 * `syncfs` 136 137New libc behavior in P (API level 28): 138 * `%C` and `%S` support in the printf family (previously only the wprintf family supported these). 139 * `%mc`/`%ms`/`%m[` support in the scanf family. 140 * `%s` support in strptime (strftime already supported it). 141 * Using a `pthread_mutex_t` after it's been destroyed will be detected at 142 runtime and reported as a FORTIFY failure. 143 * Passing a null `FILE*` or `DIR*` to libc is now detected at runtime and 144 reported as a FORTIFY failure. 145 146New libc functions in O (API level 26): 147 * `sendto` FORTIFY support 148 * `__system_property_read_callback`/`__system_property_wait` 149 * legacy `bsd_signal` 150 * `catclose`/`catgets`/`catopen` (adding <nl_types.h>) 151 * `ctermid` 152 * all 6 <grp.h>/<pwd.h> (get|set|end)(gr|pw)ent functions 153 * `futimes`/`futimesat`/`lutimes` 154 * `getdomainname`/`setdomainname` 155 * `getsubopt` 156 * `hasmntopt` 157 * `mallopt` 158 * `mblen` 159 * 4 <sys/msg.h> `msg*` functions 160 * <langinfo.h> `nl_langinfo`/`nl_langinfo_l` 161 * `pthread_getname_np` 162 * 2 new Linux system calls `quotactl` and `sync_file_range` 163 * 4 <sys/sem.h> `sem*` functions 164 * 4 <sys/shm.h> `shm*` functions 165 * 5 legacy <signal.h> functions: `sighold`/`sigignore`/`sigpause`/`sigrelse`/`sigset` 166 * `strtod_l`/`strtof_l`/`strtol_l`/`strtoul_l` 167 * <wctype.h> `towctrans`/`towctrans_l`/`wctrans`/`wctrans_l` 168 169New libc behavior in O (API level 26): 170 * Passing an invalid `pthread_t` to libc is now detected at runtime and 171 reported as a FORTIFY failure. Most commonly this is a result of confusing 172 `pthread_t` and `pid_t`. 173 174New libc functions in N (API level 24): 175 * more FORTIFY support functions (`fread`/`fwrite`/`getcwd`/`pwrite`/`write`) 176 * all remaining `_FILE_OFFSET_BITS=64` functions, completing `_FILE_OFFSET_BITS=64` support in bionic (8) 177 * all 7 `pthread_barrier*` functions 178 * all 5 `pthread_spin*` functions 179 * `lockf`/`preadv`/`pwritev`/`scandirat` and `off64_t` variants 180 * `adjtimex`/`clock_adjtime` 181 * <ifaddrs.h> `getifaddrs`/`freeifaddrs`/`if_freenameindex`/`if_nameindex` 182 * `getgrgid_r`/`getgrnam_r` 183 * GNU extensions `fileno_unlocked`/`strchrnul` 184 * 32-bit `prlimit` 185 186New libc behavior in N (API level 24): 187 * `sem_wait` now returns EINTR when interrupted by a signal. 188 189New libc functions in M (API level 23): 190 * <dirent.h> `telldir`, `seekdir`. 191 * <malloc.h> `malloc_info`. 192 * <netdb.h> `gethostbyaddr_r`, `gethostbyname2_r`. 193 * <pthread.h> `pthread_rwlockattr_getkind_np`/`pthread_rwlockattr_setkind_np`. 194 * <pty.h> `forkpty`, `openpty`. 195 * <signal.h> `sigqueue`, `sigtimedwait`, `sigwaitinfo`. 196 * <stdio.h> `fmemopen`, `open_memstream`, `feof_unlocked`, `ferror_unlocked`, `clearerr_unlocked`. 197 * <stdio_ext.h> `__flbf`, `__freadable`, `__fsetlocking`, `__fwritable`, `__fbufsize`, `__fpending`, `_flushlbf`, `__fpurge`. 198 * <stdlib.h> `mkostemp`/`mkostemps`, `lcong48`. 199 * <string.h> `basename`, `strerror_l`, `strerror_r`, `mempcpy`. 200 * <sys/sysinfo.h> `get_nprocs_conf`/`get_nprocs`, `get_phys_pages`, `get_avphys_pages`. 201 * <sys/uio.h> `process_vm_readv`/`process_vm_writev`. 202 * `clock_getcpuclockid`, `login_tty`, `mkfifoat`, `posix_madvise`, `sethostname`, `strcasecmp_l`/`strncasecmp_l`. 203 * <wchar.h> `open_wmemstream`, `wcscasecmp_l`/`wcsncasecmp_l`, `wmempcpy`. 204 * all of <error.h>. 205 * 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`. 206 207New libc functions in L (API level 21): 208 * <android/dlext.h>. 209 * <android/set_abort_message.h>. 210 * <arpa/inet.h> `inet_lnaof`, `inet_netof`, `inet_network`, `inet_makeaddr`. 211 * <wctype.h> `iswblank`. 212 * <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`. 213 * <fcntl.h> `fallocate`, `posix_fadvise`, `posix_fallocate`, `splice`, `tee`, `vmsplice`. 214 * <inttypes.h> `wcstoimax`, `wcstoumax`. 215 * <link.h> `dl_iterate_phdr`. 216 * <mntent.h> `setmntent`, `endmntent`, `getmntent_r`. 217 * <poll.h> `ppoll`. 218 * <pthread.h> `pthread_condattr_getclock`, `pthread_condattr_setclock`, `pthread_mutex_timedlock`, `pthread_gettid_np`. 219 * <sched.h> `setns`. 220 * <search.h> `insque`, `remque`, `lfind`, `lsearch`, `twalk`. 221 * <stdio.h> `dprintf`, `vdprintf`. 222 * <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`. 223 * <string.h> `strcoll_l`/`strxfrm_l`, `stpcpy`/`stpncpy`. 224 * <sys/resource.h> `prlimit`. 225 * <sys/socket.h> `accept4`, `sendmmsg`. 226 * <sys/stat.h> `mkfifo`/`mknodat`. 227 * <time.h> `strftime_l`. 228 * <unistd.h> `dup3`, `execvpe`, `getpagesize`, `linkat`/`symlinkat`/`readlinkat`, `truncate`. 229 * <wchar.h> `wcstof`, `vfwscanf`/`vswscanf`/`vwscanf`, `wcstold_l`/`wcstoll`/`wcstoll_l`/`wcstoull`/`wcstoull_l`, `mbsnrtowcs`/`wcsnrtombs`, `wcscoll_l`/`wcsxfrm_l`. 230 * <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`. 231 * all of <fts.h>. 232 * all of <locale.h>. 233 * all of <sys/epoll.h>. 234 * all of <sys/fsuid.h>. 235 * all of <sys/inotify.h>. 236 * all of <uchar.h>. 237 238New libc functions in K (API level 19): 239 * <inttypes.h> `imaxabs`, `imaxdiv`. 240 * <stdlib.h> `abs`, `labs`, `llabs`. 241 * <sys/stat.h> `futimens`. 242 * all of <sys/statvfs.h>. 243 * all of <sys/swap.h>. 244 * all of <sys/timerfd.h>. 245 246New libc functions in J-MR2 (API level 18): 247 * <stdio.h> `getdelim` and `getline`. 248 * <sys/auxv.h> `getauxval`. 249 * <sys/signalfd.h> `signalfd`. 250 251New libc functions in J-MR1 (API level 17): 252 * <ftw.h>. 253 * <signal.h> `psiginfo` and `psignal`. 254 * `getsid`, `malloc_usable_size`, `mlockall`/`munlockall`, `posix_memalign`, `unshare`. 255 256New libc functions in J (API level 16): 257 * the <search.h> tree functions `tdelete`, `tdestroy`, `tfind`, and `tsearch`. 258 * `faccessat`, `readahead`, `tgkill`. 259 * all of <sys/xattr.h>. 260 261libc function count over time: 262 263| OS | API level | Function count | 264|-------|-----------|----------------| 265| J | 16 | 842 | 266| J MR1 | 17 | 870 | 267| J MR2 | 18 | 878 | 268| K | 19 | 893 | 269| L | 21 | 1118 | 270| M | 23 | 1183 | 271| N | 24 | 1228 | 272| O | 26 | 1280 | 273| P | 28 | 1378 | 274| Q | 29 | 1394 | 275 276Data collected by: 277``` 278ndk-r21$ for i in `ls -1v platforms/android-*/arch-arm/usr/lib/libc.so` ; do \ 279 echo $i; nm $i | grep -w T | wc -l ; done 280``` 281 282### libm 283 284Current libm symbols: https://android.googlesource.com/platform/bionic/+/master/libm/libm.map.txt 285 2860 remaining missing C11/POSIX libm functions. 287 288New libm functions in O (API level 26): 289 * <complex.h> `clog`/`clogf`, `cpow`/`cpowf` functions. 290 291New libm functions in M (API level 23): 292 * <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`. 293 * <math.h> `lgammal_r`. 294 295New libm functions in L (API level 21): 296 * <complex.h> `cabsl`, `cprojl`, `csqrtl`. 297 * <math.h> `isinf`, `significandl`. 298 299New libm functions in J-MR2 (API level 18): 300 * <math.h> `log2`, `log2f`. 301 302 303## Target API level behavioral differences 304 305Most bionic bug fixes and improvements have been made without checks for 306the app's `targetSdkVersion`. As of O there were exactly two exceptions, 307but there are likely to be more in future because of Project Treble. 308 309### Invalid `pthread_t` handling (targetSdkVersion >= O) 310 311As part of a long-term goal to remove the global thread list, 312and in an attempt to flush out racy code, we changed how an invalid 313`pthread_t` is handled. For `pthread_detach`, `pthread_getcpuclockid`, 314`pthread_getschedparam`/`pthread_setschedparam`, `pthread_join`, and 315`pthread_kill`, instead of returning ESRCH when passed an invalid 316`pthread_t`, if you're targeting O or above, they'll abort with the 317message "attempt to use invalid pthread\_t". 318 319Note that this doesn't change behavior as much as you might think: the 320old lookup only held the global thread list lock for the duration of 321the lookup, so there was still a race between that and the dereference 322in the caller, given that callers actually need the tid to pass to some 323syscall or other, and sometimes update fields in the `pthread_internal_t` 324struct too. 325 326We can't check a thread's tid against 0 to see whether a `pthread_t` 327is still valid because a dead thread gets its thread struct unmapped 328along with its stack, so the dereference isn't safe. 329 330To fix your code, taking the affected functions one by one: 331 332 * `pthread_getcpuclockid` and `pthread_getschedparam`/`pthread_setschedparam` 333 should be fine. Unsafe calls to those seem highly unlikely. 334 335 * Unsafe `pthread_detach` callers probably want to switch to 336 `pthread_attr_setdetachstate` instead, or use 337 `pthread_detach(pthread_self());` from the new thread's start routine 338 rather than calling detach in the parent. 339 340 * `pthread_join` calls should be safe anyway, because a joinable thread 341 won't actually exit and unmap until it's joined. If you're joining an 342 unjoinable thread, the fix is to stop marking it detached. If you're 343 joining an already-joined thread, you need to rethink your design! 344 345 * Unsafe `pthread_kill` calls aren't portably fixable. (And are obviously 346 inherently non-portable as-is.) The best alternative on Android is to 347 use `pthread_gettid_np` at some point that you know the thread to be 348 alive, and then call `kill`/`tgkill` with signal 0 (which checks 349 whether a process exists rather than actually sending a 350 signal). That's still not completely safe because if you're too late 351 the tid may have been reused, but your code is inherently unsafe without 352 a redesign anyway. 353 354### Interruptable `sem_wait` (targetSdkVersion >= N) 355 356POSIX says that `sem_wait` can be interrupted by delivery of a 357signal. This wasn't historically true in Android, and when we fixed this 358bug we found that existing code relied on the old behavior. To preserve 359compatibility, `sem_wait` can only return EINTR on Android if the app 360targets N or later. 361 362 363## FORTIFY 364 365The `_FORTIFY_SOURCE` macro can be used to enable extra 366automatic bounds checking for common libc functions. If a buffer 367overrun is detected, the program is safely aborted as in this 368[example](https://source.android.com/devices/tech/debug/native-crash#fortify). 369 370Note that in recent releases Android's FORTIFY has been extended to 371cover other issues. It can now detect, for example, passing `O_CREAT` 372to open(2) without specifying a mode. It also performs some checking 373regardless of whether the caller was built with FORTIFY enabled. In P, 374for example, calling a `pthread_mutex_` function on a destroyed mutex, 375calling a `<dirent.h>` function on a null pointer, using `%n` with the 376printf(3) family, or using the scanf(3) `m` modifier incorrectly will 377all result in FORTIFY failures even for code not built with FORTIFY. 378 379More background information is available in our 380[FORTIFY in Android](https://android-developers.googleblog.com/2017/04/fortify-in-android.html) 381blog post. 382 383The Android platform is built with `-D_FORTIFY_SOURCE=2`, but NDK users 384need to manually enable FORTIFY by setting that themselves in whatever 385build system they're using. The exact subset of FORTIFY available to 386NDK users will depend on their target ABI level, because when a FORTIFY 387check can't be guaranteed at compile-time, a call to a run-time `_chk` 388function is added. 389