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
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 P:
41  * `__freading`/`__fwriting` (completing <stdio_ext.h>)
42  * `endhostent`/`endnetent`/`endprotoent`/`getnetent`/`getprotoent`/`sethostent`/`setnetent`/`setprotoent` (completing <netdb.h>)
43  * `fexecve`
44  * `fflush_unlocked`/`fgetc_unlocked`/`fgets_unlocked`/`fputc_unlocked`/`fputs_unlocked`/`fread_unlocked`/`fwrite_unlocked`
45  * `getentropy`/`getrandom` (adding <sys/random.h>)
46  * `getlogin_r`
47  * `glob`/`globfree` (adding <glob.h>)
48  * `hcreate`/`hcreate_r`/`hdestroy`/`hdestroy_r`/`hsearch`/`hsearch_r` (completing <search.h>)
49  * `iconv`/`iconv_close`/`iconv_open` (adding <iconv.h>)
50  * `pthread_attr_getinheritsched`/`pthread_attr_setinheritsched`/`pthread_setschedprio`
51  * `pthread_mutexattr_getprotocol`/`pthread_mutexattr_setprotocol` (mutex priority inheritance)
52  * <signal.h> support for `sigaction64_t` and `sigset64_t` allowing LP32 access to real-time signals
53  * <spawn.h>
54  * `swab`
55  * `syncfs`
56
57New libc behavior in P:
58  * `%C` and `%S` support in the printf family (previously only the wprintf family supported these)
59  * `%mc`/`%ms`/`%m[` support in the scanf family
60  * `%s` support in strptime (strftime already supported it)
61
62New libc functions in O:
63  * `sendto` FORTIFY support
64  * `__system_property_read_callback`/`__system_property_wait`
65  * legacy `bsd_signal`
66  * `catclose`/`catgets`/`catopen` (adding <nl_types.h>)
67  * `ctermid`
68  * all 6 <grp.h>/<pwd.h> (get|set|end)(gr|pw)ent functions
69  * `futimes`/`futimesat`/`lutimes`
70  * `getdomainname`/`setdomainname`
71  * `getsubopt`
72  * `hasmntopt`
73  * `mallopt`
74  * `mblen`
75  * 4 <sys/msg.h> `msg*` functions
76  * <langinfo.h> `nl_langinfo`/`nl_langinfo_l`
77  * `pthread_getname_np`
78  * 2 new Linux system calls `quotactl` and `sync_file_range`
79  * 4 <sys/sem.h> `sem*` functions
80  * 4 <sys/shm.h> `shm*` functions
81  * 5 legacy <signal.h> functions: `sighold`/`sigignore`/`sigpause`/`sigrelse`/`sigset`
82  * `strtod_l`/`strtof_l`/`strtol_l`/`strtoul_l`
83  * <wctype.h> `towctrans`/`towctrans_l`/`wctrans`/`wctrans_l`
84
85New libc functions in N:
86  * more FORTIFY support functions (`fread`/`fwrite`/`getcwd`/`pwrite`/`write`)
87  * all remaining `_FILE_OFFSET_BITS=64` functions, completing `_FILE_OFFSET_BITS=64` support in bionic (8)
88  * all 7 `pthread_barrier*` functions
89  * all 5 `pthread_spin*` functions
90  * `lockf`/`preadv`/`pwritev`/`scandirat` and `off64_t` variants
91  * `adjtimex`/`clock_adjtime`
92  * `getifaddrs`/`freeifaddrs`/`if_freenameindex`/`if_nameindex`
93  * `getgrgid_r`/`getgrnam_r`
94  * GNU extensions `fileno_unlocked`/`strchrnul`
95  * 32-bit `prlimit`
96
97libc function count over time:
98  G 803, H 825, I 826, J 846, J-MR1 873, J-MR2 881, K 896, L 1116, M 1181, N 1226, O 1278
99
100```
101ndk-r17$ for i in `ls -1v platforms/android-*/arch-arm/usr/lib/libc.so` ; do \
102  echo $i; nm $i | grep -vw [AbdNnt] | grep -vw B | wc -l ; done
103```
104
105### libm
106
107Current libm symbols: https://android.googlesource.com/platform/bionic/+/master/libm/libm.map.txt
108
1090 remaining missing POSIX libm functions.
110
11119 new libm functions in O: complex trig/exp/log functions.
112
113libm function count over time:
114  G 158, J-MR2 164, L 220, M 265, O 284
115
116
117
118## Target API level behavioral differences
119
120Most bionic bug fixes and improvements have been made without checks for
121the app's `targetSdkVersion`. As of O there were exactly two exceptions,
122but there are likely to be more in future because of Project Treble.
123
124### Invalid `pthread_t` handling (targetSdkVersion >= O)
125
126As part of a long-term goal to remove the global thread list,
127and in an attempt to flush out racy code, we changed how an invalid
128`pthread_t` is handled. For `pthread_detach`, `pthread_getcpuclockid`,
129`pthread_getschedparam`/`pthread_setschedparam`, `pthread_join`, and
130`pthread_kill`, instead of returning ESRCH when passed an invalid
131`pthread_t`, if you're targeting O or above, they'll abort with the
132message "attempt to use invalid pthread\_t".
133
134Note that this doesn't change behavior as much as you might think: the
135old lookup only held the global thread list lock for the duration of
136the lookup, so there was still a race between that and the dereference
137in the caller, given that callers actually need the tid to pass to some
138syscall or other, and sometimes update fields in the `pthread_internal_t`
139struct too.
140
141We can't check a thread's tid against 0 to see whether a `pthread_t`
142is still valid because a dead thread gets its thread struct unmapped
143along with its stack, so the dereference isn't safe.
144
145To fix your code, taking the affected functions one by one:
146
147  * `pthread_getcpuclockid` and `pthread_getschedparam`/`pthread_setschedparam`
148    should be fine. Unsafe calls to those seem highly unlikely.
149
150  * Unsafe `pthread_detach` callers probably want to switch to
151    `pthread_attr_setdetachstate` instead, or use
152    `pthread_detach(pthread_self());` from the new thread's start routine
153    rather than calling detach in the parent.
154
155  * `pthread_join` calls should be safe anyway, because a joinable thread
156    won't actually exit and unmap until it's joined. If you're joining an
157    unjoinable thread, the fix is to stop marking it detached. If you're
158    joining an already-joined thread, you need to rethink your design!
159
160  * Unsafe `pthread_kill` calls aren't portably fixable. (And are obviously
161    inherently non-portable as-is.) The best alternative on Android is to
162    use `pthread_gettid_np` at some point that you know the thread to be
163    alive, and then call `kill`/`tgkill` with signal 0 (which checks
164    whether a process exists rather than actually sending a
165    signal). That's still not completely safe because if you're too late
166    the tid may have been reused, but your code is inherently unsafe without
167    a redesign anyway.
168
169### Interruptable `sem_wait` (targetSdkVersion >= N)
170
171POSIX says that `sem_wait` can be interrupted by delivery of a
172signal. This wasn't historically true in Android, and when we fixed this
173bug we found that existing code relied on the old behavior. To preserve
174compatibility, `sem_wait` can only return EINTR on Android if the app
175targets N or later.
176