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