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