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