1 /*
2 * Copyright (C) 2012 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #pragma once
18
19 /**
20 * @file malloc.h
21 * @brief Heap memory allocation.
22 *
23 * [Debugging Native Memory Use](https://source.android.com/devices/tech/debug/native-memory)
24 * is the canonical source for documentation on Android's heap debugging
25 * features.
26 */
27
28 #include <sys/cdefs.h>
29 #include <stddef.h>
30 #include <stdio.h>
31
32 __BEGIN_DECLS
33
34 #define __BIONIC_ALLOC_SIZE(...) __attribute__((__alloc_size__(__VA_ARGS__)))
35
36 /**
37 * [malloc(3)](https://man7.org/linux/man-pages/man3/malloc.3.html) allocates
38 * memory on the heap.
39 *
40 * Returns a pointer to the allocated memory on success and returns a null
41 * pointer and sets `errno` on failure.
42 *
43 * Note that Android (like most Unix systems) allows "overcommit". This
44 * allows processes to allocate more memory than the system has, provided
45 * they don't use it all. This works because only "dirty" pages that have
46 * been written to actually require physical memory. In practice, this
47 * means that it's rare to see memory allocation functions return a null
48 * pointer, and that a non-null pointer does not mean that you actually
49 * have all of the memory you asked for.
50 *
51 * Note also that the Linux Out Of Memory (OOM) killer behaves differently
52 * for code run via `adb shell`. The assumption is that if you ran
53 * something via `adb shell` you're a developer who actually wants the
54 * device to do what you're asking it to do _even if_ that means killing
55 * other processes. Obviously this is not the case for apps, which will
56 * be killed in preference to killing other processes.
57 */
58 __nodiscard void* _Nullable malloc(size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(1);
59
60 /**
61 * [calloc(3)](https://man7.org/linux/man-pages/man3/calloc.3.html) allocates
62 * and clears memory on the heap.
63 *
64 * Returns a pointer to the allocated memory on success and returns a null
65 * pointer and sets `errno` on failure (but see the notes for malloc()).
66 */
67 __nodiscard void* _Nullable calloc(size_t __item_count, size_t __item_size) __mallocfunc __BIONIC_ALLOC_SIZE(1,2);
68
69 /**
70 * [realloc(3)](https://man7.org/linux/man-pages/man3/realloc.3.html) resizes
71 * allocated memory on the heap.
72 *
73 * Returns a pointer (which may be different from `__ptr`) to the resized
74 * memory on success and returns a null pointer and sets `errno` on failure
75 * (but see the notes for malloc()).
76 */
77 __nodiscard void* _Nullable realloc(void* _Nullable __ptr, size_t __byte_count) __BIONIC_ALLOC_SIZE(2);
78
79 /**
80 * [reallocarray(3)](https://man7.org/linux/man-pages/man3/realloc.3.html) resizes
81 * allocated memory on the heap.
82 *
83 * Equivalent to `realloc(__ptr, __item_count * __item_size)` but fails if the
84 * multiplication overflows.
85 *
86 * Returns a pointer (which may be different from `__ptr`) to the resized
87 * memory on success and returns a null pointer and sets `errno` on failure
88 * (but see the notes for malloc()).
89 */
90 #if __ANDROID_API__ >= 29
91 __nodiscard void* _Nullable reallocarray(void* _Nullable __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) __INTRODUCED_IN(29);
92 #elif defined(__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__)
93 #include <errno.h>
reallocarray(void * _Nullable __ptr,size_t __item_count,size_t __item_size)94 static __inline __nodiscard void* _Nullable reallocarray(void* _Nullable __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) {
95 size_t __new_size;
96 if (__builtin_mul_overflow(__item_count, __item_size, &__new_size)) {
97 errno = ENOMEM;
98 return NULL;
99 }
100 return realloc(__ptr, __new_size);
101 }
102 #endif
103
104 /**
105 * [free(3)](https://man7.org/linux/man-pages/man3/free.3.html) deallocates
106 * memory on the heap.
107 */
108 void free(void* _Nullable __ptr);
109
110 /**
111 * [memalign(3)](https://man7.org/linux/man-pages/man3/memalign.3.html) allocates
112 * memory on the heap with the required alignment.
113 *
114 * Returns a pointer to the allocated memory on success and returns a null
115 * pointer and sets `errno` on failure (but see the notes for malloc()).
116 *
117 * See also posix_memalign().
118 */
119 __nodiscard void* _Nullable memalign(size_t __alignment, size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(2);
120
121 /**
122 * [malloc_usable_size(3)](https://man7.org/linux/man-pages/man3/malloc_usable_size.3.html)
123 * returns the actual size of the given heap block.
124 */
125 __nodiscard size_t malloc_usable_size(const void* _Nullable __ptr);
126
127 #define __MALLINFO_BODY \
128 /** Total number of non-mmapped bytes currently allocated from OS. */ \
129 size_t arena; \
130 /** Number of free chunks. */ \
131 size_t ordblks; \
132 /** (Unused.) */ \
133 size_t smblks; \
134 /** (Unused.) */ \
135 size_t hblks; \
136 /** Total number of bytes in mmapped regions. */ \
137 size_t hblkhd; \
138 /** Maximum total allocated space; greater than total if trimming has occurred. */ \
139 size_t usmblks; \
140 /** (Unused.) */ \
141 size_t fsmblks; \
142 /** Total allocated space (normal or mmapped.) */ \
143 size_t uordblks; \
144 /** Total free space. */ \
145 size_t fordblks; \
146 /** Upper bound on number of bytes releasable by a trim operation. */ \
147 size_t keepcost;
148
149 #ifndef STRUCT_MALLINFO_DECLARED
150 #define STRUCT_MALLINFO_DECLARED 1
151 struct mallinfo { __MALLINFO_BODY };
152 #endif
153
154 /**
155 * [mallinfo(3)](https://man7.org/linux/man-pages/man3/mallinfo.3.html) returns
156 * information about the current state of the heap. Note that mallinfo() is
157 * inherently unreliable and consider using malloc_info() instead.
158 */
159 struct mallinfo mallinfo(void);
160
161 /**
162 * On Android the struct mallinfo and struct mallinfo2 are the same.
163 */
164 struct mallinfo2 { __MALLINFO_BODY };
165
166 /**
167 * [mallinfo2(3)](https://man7.org/linux/man-pages/man3/mallinfo2.3.html) returns
168 * information about the current state of the heap. Note that mallinfo2() is
169 * inherently unreliable and consider using malloc_info() instead.
170 */
171 struct mallinfo2 mallinfo2(void) __RENAME(mallinfo);
172
173 /**
174 * [malloc_info(3)](https://man7.org/linux/man-pages/man3/malloc_info.3.html)
175 * writes information about the current state of the heap to the given stream.
176 *
177 * The XML structure for malloc_info() is as follows:
178 * ```
179 * <malloc version="jemalloc-1">
180 * <heap nr="INT">
181 * <allocated-large>INT</allocated-large>
182 * <allocated-huge>INT</allocated-huge>
183 * <allocated-bins>INT</allocated-bins>
184 * <bins-total>INT</bins-total>
185 * <bin nr="INT">
186 * <allocated>INT</allocated>
187 * <nmalloc>INT</nmalloc>
188 * <ndalloc>INT</ndalloc>
189 * </bin>
190 * <!-- more bins -->
191 * </heap>
192 * <!-- more heaps -->
193 * </malloc>
194 * ```
195 *
196 * Available since API level 23.
197 */
198
199 #if __BIONIC_AVAILABILITY_GUARD(23)
200 int malloc_info(int __must_be_zero, FILE* _Nonnull __fp) __INTRODUCED_IN(23);
201 #endif /* __BIONIC_AVAILABILITY_GUARD(23) */
202
203
204 /**
205 * mallopt() option to set the decay time. Valid values are -1, 0 and 1.
206 * -1 : Disable the releasing of unused pages. This value is available since
207 * API level 35.
208 * 0 : Release the unused pages immediately.
209 * 1 : Release the unused pages at a device-specific interval.
210 *
211 * Available since API level 27.
212 */
213 #define M_DECAY_TIME (-100)
214 /**
215 * mallopt() option to immediately purge any memory not in use. This
216 * will release the memory back to the kernel. The value is ignored.
217 *
218 * Available since API level 28.
219 */
220 #define M_PURGE (-101)
221 /**
222 * mallopt() option to immediately purge all possible memory back to
223 * the kernel. This call can take longer than a normal purge since it
224 * examines everything. In some cases, it can take more than twice the
225 * time of a M_PURGE call. The value is ignored.
226 *
227 * Available since API level 34.
228 */
229 #define M_PURGE_ALL (-104)
230
231 /**
232 * mallopt() option to tune the allocator's choice of memory tags to
233 * make it more likely that a certain class of memory errors will be
234 * detected. This is only relevant if MTE is enabled in this process
235 * and ignored otherwise. The value argument should be one of the
236 * M_MEMTAG_TUNING_* flags.
237 * NOTE: This is only available in scudo.
238 *
239 * Available since API level 31.
240 */
241 #define M_MEMTAG_TUNING (-102)
242
243 /**
244 * When passed as a value of M_MEMTAG_TUNING mallopt() call, enables
245 * deterministic detection of linear buffer overflow and underflow
246 * bugs by assigning distinct tag values to adjacent allocations. This
247 * mode has a slightly reduced chance to detect use-after-free bugs
248 * because only half of the possible tag values are available for each
249 * memory location.
250 *
251 * Please keep in mind that MTE can not detect overflow within the
252 * same tag granule (16-byte aligned chunk), and can miss small
253 * overflows even in this mode. Such overflow can not be the cause of
254 * a memory corruption, because the memory within one granule is never
255 * used for multiple allocations.
256 */
257 #define M_MEMTAG_TUNING_BUFFER_OVERFLOW 0
258
259 /**
260 * When passed as a value of M_MEMTAG_TUNING mallopt() call, enables
261 * independently randomized tags for uniform ~93% probability of
262 * detecting both spatial (buffer overflow) and temporal (use after
263 * free) bugs.
264 */
265 #define M_MEMTAG_TUNING_UAF 1
266
267 /**
268 * mallopt() option for per-thread memory initialization tuning.
269 * The value argument should be one of:
270 * 1: Disable automatic heap initialization on this thread only.
271 * If memory tagging is enabled, disable as much as possible of the
272 * memory tagging initialization for this thread.
273 * 0: Normal behavior.
274 *
275 * Available since API level 31.
276 */
277 #define M_THREAD_DISABLE_MEM_INIT (-103)
278 /**
279 * mallopt() option to set the maximum number of items in the secondary
280 * cache of the scudo allocator.
281 *
282 * Available since API level 31.
283 */
284 #define M_CACHE_COUNT_MAX (-200)
285 /**
286 * mallopt() option to set the maximum size in bytes of a cacheable item in
287 * the secondary cache of the scudo allocator.
288 *
289 * Available since API level 31.
290 */
291 #define M_CACHE_SIZE_MAX (-201)
292 /**
293 * mallopt() option to increase the maximum number of shared thread-specific
294 * data structures that can be created. This number cannot be decreased,
295 * only increased and only applies to the scudo allocator.
296 *
297 * Available since API level 31.
298 */
299 #define M_TSDS_COUNT_MAX (-202)
300
301 /**
302 * mallopt() option to decide whether heap memory is zero-initialized on
303 * allocation across the whole process. May be called at any time, including
304 * when multiple threads are running. An argument of zero indicates memory
305 * should not be zero-initialized, any other value indicates to initialize heap
306 * memory to zero.
307 *
308 * Note that this memory mitigation is only implemented in scudo and therefore
309 * this will have no effect when using another allocator (such as jemalloc on
310 * Android Go devices).
311 *
312 * Available since API level 31.
313 */
314 #define M_BIONIC_ZERO_INIT (-203)
315
316 /**
317 * mallopt() option to change the heap tagging state. May be called at any
318 * time, including when multiple threads are running.
319 * The value must be one of the M_HEAP_TAGGING_LEVEL_ constants.
320 * NOTE: This is only available in scudo.
321 *
322 * Available since API level 31.
323 */
324 #define M_BIONIC_SET_HEAP_TAGGING_LEVEL (-204)
325
326 /**
327 * Constants for use with the M_BIONIC_SET_HEAP_TAGGING_LEVEL mallopt() option.
328 */
329 enum HeapTaggingLevel {
330 /**
331 * Disable heap tagging and memory tag checks (if supported).
332 * Heap tagging may not be re-enabled after being disabled.
333 */
334 M_HEAP_TAGGING_LEVEL_NONE = 0,
335 #define M_HEAP_TAGGING_LEVEL_NONE M_HEAP_TAGGING_LEVEL_NONE
336 /**
337 * Address-only tagging. Heap pointers have a non-zero tag in the
338 * most significant ("top") byte which is checked in free(). Memory
339 * accesses ignore the tag using arm64's Top Byte Ignore (TBI) feature.
340 */
341 M_HEAP_TAGGING_LEVEL_TBI = 1,
342 #define M_HEAP_TAGGING_LEVEL_TBI M_HEAP_TAGGING_LEVEL_TBI
343 /**
344 * Enable heap tagging and asynchronous memory tag checks (if supported).
345 * Disable stack trace collection.
346 */
347 M_HEAP_TAGGING_LEVEL_ASYNC = 2,
348 #define M_HEAP_TAGGING_LEVEL_ASYNC M_HEAP_TAGGING_LEVEL_ASYNC
349 /**
350 * Enable heap tagging and synchronous memory tag checks (if supported).
351 * Enable stack trace collection.
352 */
353 M_HEAP_TAGGING_LEVEL_SYNC = 3,
354 #define M_HEAP_TAGGING_LEVEL_SYNC M_HEAP_TAGGING_LEVEL_SYNC
355 };
356
357 /**
358 * mallopt() option to print human readable statistics about the memory
359 * allocator to the log. There is no format for this data, each allocator
360 * can use a different format, and the data that is printed can
361 * change at any time. This is expected to be used as a debugging aid.
362 *
363 * Available since API level 35.
364 */
365 #define M_LOG_STATS (-205)
366
367 /**
368 * [mallopt(3)](https://man7.org/linux/man-pages/man3/mallopt.3.html) modifies
369 * heap behavior. Values of `__option` are the `M_` constants from this header.
370 *
371 * Returns 1 on success, 0 on error.
372 *
373 * Available since API level 26.
374 */
375
376 #if __BIONIC_AVAILABILITY_GUARD(26)
377 int mallopt(int __option, int __value) __INTRODUCED_IN(26);
378 #endif /* __BIONIC_AVAILABILITY_GUARD(26) */
379
380
381 /**
382 * [__malloc_hook(3)](https://man7.org/linux/man-pages/man3/__malloc_hook.3.html)
383 * is called to implement malloc(). By default this points to the system's
384 * implementation.
385 *
386 * Available since API level 28.
387 *
388 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md)
389 */
390
391 #if __BIONIC_AVAILABILITY_GUARD(28)
392 extern void* _Nonnull (*volatile _Nonnull __malloc_hook)(size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
393
394 /**
395 * [__realloc_hook(3)](https://man7.org/linux/man-pages/man3/__realloc_hook.3.html)
396 * is called to implement realloc(). By default this points to the system's
397 * implementation.
398 *
399 * Available since API level 28.
400 *
401 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md)
402 */
403 extern void* _Nonnull (*volatile _Nonnull __realloc_hook)(void* _Nullable __ptr, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
404
405 /**
406 * [__free_hook(3)](https://man7.org/linux/man-pages/man3/__free_hook.3.html)
407 * is called to implement free(). By default this points to the system's
408 * implementation.
409 *
410 * Available since API level 28.
411 *
412 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md)
413 */
414 extern void (*volatile _Nonnull __free_hook)(void* _Nullable __ptr, const void* _Nonnull __caller) __INTRODUCED_IN(28);
415
416 /**
417 * [__memalign_hook(3)](https://man7.org/linux/man-pages/man3/__memalign_hook.3.html)
418 * is called to implement memalign(). By default this points to the system's
419 * implementation.
420 *
421 * Available since API level 28.
422 *
423 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md)
424 */
425 extern void* _Nonnull (*volatile _Nonnull __memalign_hook)(size_t __alignment, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
426 #endif /* __BIONIC_AVAILABILITY_GUARD(28) */
427
428
429 __END_DECLS
430