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)](http://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 void* _Nullable malloc(size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(1) __wur; 59 60 /** 61 * [calloc(3)](http://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 void* _Nullable calloc(size_t __item_count, size_t __item_size) __mallocfunc __BIONIC_ALLOC_SIZE(1,2) __wur; 68 69 /** 70 * [realloc(3)](http://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 void* _Nullable realloc(void* _Nullable __ptr, size_t __byte_count) __BIONIC_ALLOC_SIZE(2) __wur; 78 79 /** 80 * [reallocarray(3)](http://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 void* _Nullable reallocarray(void* _Nullable __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) __wur __INTRODUCED_IN(29); 91 92 /** 93 * [free(3)](http://man7.org/linux/man-pages/man3/free.3.html) deallocates 94 * memory on the heap. 95 */ 96 void free(void* _Nullable __ptr); 97 98 /** 99 * [memalign(3)](http://man7.org/linux/man-pages/man3/memalign.3.html) allocates 100 * memory on the heap with the required alignment. 101 * 102 * Returns a pointer to the allocated memory on success and returns a null 103 * pointer and sets `errno` on failure (but see the notes for malloc()). 104 * 105 * See also posix_memalign(). 106 */ 107 void* _Nullable memalign(size_t __alignment, size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(2) __wur; 108 109 /** 110 * [malloc_usable_size(3)](http://man7.org/linux/man-pages/man3/malloc_usable_size.3.html) 111 * returns the actual size of the given heap block. 112 */ 113 size_t malloc_usable_size(const void* _Nullable __ptr) __wur; 114 115 #define __MALLINFO_BODY \ 116 /** Total number of non-mmapped bytes currently allocated from OS. */ \ 117 size_t arena; \ 118 /** Number of free chunks. */ \ 119 size_t ordblks; \ 120 /** (Unused.) */ \ 121 size_t smblks; \ 122 /** (Unused.) */ \ 123 size_t hblks; \ 124 /** Total number of bytes in mmapped regions. */ \ 125 size_t hblkhd; \ 126 /** Maximum total allocated space; greater than total if trimming has occurred. */ \ 127 size_t usmblks; \ 128 /** (Unused.) */ \ 129 size_t fsmblks; \ 130 /** Total allocated space (normal or mmapped.) */ \ 131 size_t uordblks; \ 132 /** Total free space. */ \ 133 size_t fordblks; \ 134 /** Upper bound on number of bytes releasable by a trim operation. */ \ 135 size_t keepcost; 136 137 #ifndef STRUCT_MALLINFO_DECLARED 138 #define STRUCT_MALLINFO_DECLARED 1 139 struct mallinfo { __MALLINFO_BODY }; 140 #endif 141 142 /** 143 * [mallinfo(3)](http://man7.org/linux/man-pages/man3/mallinfo.3.html) returns 144 * information about the current state of the heap. Note that mallinfo() is 145 * inherently unreliable and consider using malloc_info() instead. 146 */ 147 struct mallinfo mallinfo(void); 148 149 /** 150 * On Android the struct mallinfo and struct mallinfo2 are the same. 151 */ 152 struct mallinfo2 { __MALLINFO_BODY }; 153 154 /** 155 * [mallinfo2(3)](http://man7.org/linux/man-pages/man3/mallinfo2.3.html) returns 156 * information about the current state of the heap. Note that mallinfo2() is 157 * inherently unreliable and consider using malloc_info() instead. 158 */ 159 struct mallinfo2 mallinfo2(void) __RENAME(mallinfo); 160 161 /** 162 * [malloc_info(3)](http://man7.org/linux/man-pages/man3/malloc_info.3.html) 163 * writes information about the current state of the heap to the given stream. 164 * 165 * The XML structure for malloc_info() is as follows: 166 * ``` 167 * <malloc version="jemalloc-1"> 168 * <heap nr="INT"> 169 * <allocated-large>INT</allocated-large> 170 * <allocated-huge>INT</allocated-huge> 171 * <allocated-bins>INT</allocated-bins> 172 * <bins-total>INT</bins-total> 173 * <bin nr="INT"> 174 * <allocated>INT</allocated> 175 * <nmalloc>INT</nmalloc> 176 * <ndalloc>INT</ndalloc> 177 * </bin> 178 * <!-- more bins --> 179 * </heap> 180 * <!-- more heaps --> 181 * </malloc> 182 * ``` 183 * 184 * Available since API level 23. 185 */ 186 int malloc_info(int __must_be_zero, FILE* _Nonnull __fp) __INTRODUCED_IN(23); 187 188 /** 189 * mallopt() option to set the decay time. Valid values are -1, 0 and 1. 190 * -1 : Disable the releasing of unused pages. This value is available since 191 * API level 35. 192 * 0 : Release the unused pages immediately. 193 * 1 : Release the unused pages at a device-specific interval. 194 * 195 * Available since API level 27. 196 */ 197 #define M_DECAY_TIME (-100) 198 /** 199 * mallopt() option to immediately purge any memory not in use. This 200 * will release the memory back to the kernel. The value is ignored. 201 * 202 * Available since API level 28. 203 */ 204 #define M_PURGE (-101) 205 /** 206 * mallopt() option to immediately purge all possible memory back to 207 * the kernel. This call can take longer than a normal purge since it 208 * examines everything. In some cases, it can take more than twice the 209 * time of a M_PURGE call. The value is ignored. 210 * 211 * Available since API level 34. 212 */ 213 #define M_PURGE_ALL (-104) 214 215 /** 216 * mallopt() option to tune the allocator's choice of memory tags to 217 * make it more likely that a certain class of memory errors will be 218 * detected. This is only relevant if MTE is enabled in this process 219 * and ignored otherwise. The value argument should be one of the 220 * M_MEMTAG_TUNING_* flags. 221 * NOTE: This is only available in scudo. 222 * 223 * Available since API level 31. 224 */ 225 #define M_MEMTAG_TUNING (-102) 226 227 /** 228 * When passed as a value of M_MEMTAG_TUNING mallopt() call, enables 229 * deterministic detection of linear buffer overflow and underflow 230 * bugs by assigning distinct tag values to adjacent allocations. This 231 * mode has a slightly reduced chance to detect use-after-free bugs 232 * because only half of the possible tag values are available for each 233 * memory location. 234 * 235 * Please keep in mind that MTE can not detect overflow within the 236 * same tag granule (16-byte aligned chunk), and can miss small 237 * overflows even in this mode. Such overflow can not be the cause of 238 * a memory corruption, because the memory within one granule is never 239 * used for multiple allocations. 240 */ 241 #define M_MEMTAG_TUNING_BUFFER_OVERFLOW 0 242 243 /** 244 * When passed as a value of M_MEMTAG_TUNING mallopt() call, enables 245 * independently randomized tags for uniform ~93% probability of 246 * detecting both spatial (buffer overflow) and temporal (use after 247 * free) bugs. 248 */ 249 #define M_MEMTAG_TUNING_UAF 1 250 251 /** 252 * mallopt() option for per-thread memory initialization tuning. 253 * The value argument should be one of: 254 * 1: Disable automatic heap initialization on this thread only. 255 * If memory tagging is enabled, disable as much as possible of the 256 * memory tagging initialization for this thread. 257 * 0: Normal behavior. 258 * 259 * Available since API level 31. 260 */ 261 #define M_THREAD_DISABLE_MEM_INIT (-103) 262 /** 263 * mallopt() option to set the maximum number of items in the secondary 264 * cache of the scudo allocator. 265 * 266 * Available since API level 31. 267 */ 268 #define M_CACHE_COUNT_MAX (-200) 269 /** 270 * mallopt() option to set the maximum size in bytes of a cacheable item in 271 * the secondary cache of the scudo allocator. 272 * 273 * Available since API level 31. 274 */ 275 #define M_CACHE_SIZE_MAX (-201) 276 /** 277 * mallopt() option to increase the maximum number of shared thread-specific 278 * data structures that can be created. This number cannot be decreased, 279 * only increased and only applies to the scudo allocator. 280 * 281 * Available since API level 31. 282 */ 283 #define M_TSDS_COUNT_MAX (-202) 284 285 /** 286 * mallopt() option to decide whether heap memory is zero-initialized on 287 * allocation across the whole process. May be called at any time, including 288 * when multiple threads are running. An argument of zero indicates memory 289 * should not be zero-initialized, any other value indicates to initialize heap 290 * memory to zero. 291 * 292 * Note that this memory mitigation is only implemented in scudo and therefore 293 * this will have no effect when using another allocator (such as jemalloc on 294 * Android Go devices). 295 * 296 * Available since API level 31. 297 */ 298 #define M_BIONIC_ZERO_INIT (-203) 299 300 /** 301 * mallopt() option to change the heap tagging state. May be called at any 302 * time, including when multiple threads are running. 303 * The value must be one of the M_HEAP_TAGGING_LEVEL_ constants. 304 * NOTE: This is only available in scudo. 305 * 306 * Available since API level 31. 307 */ 308 #define M_BIONIC_SET_HEAP_TAGGING_LEVEL (-204) 309 310 /** 311 * Constants for use with the M_BIONIC_SET_HEAP_TAGGING_LEVEL mallopt() option. 312 */ 313 enum HeapTaggingLevel { 314 /** 315 * Disable heap tagging and memory tag checks (if supported). 316 * Heap tagging may not be re-enabled after being disabled. 317 */ 318 M_HEAP_TAGGING_LEVEL_NONE = 0, 319 #define M_HEAP_TAGGING_LEVEL_NONE M_HEAP_TAGGING_LEVEL_NONE 320 /** 321 * Address-only tagging. Heap pointers have a non-zero tag in the 322 * most significant ("top") byte which is checked in free(). Memory 323 * accesses ignore the tag using arm64's Top Byte Ignore (TBI) feature. 324 */ 325 M_HEAP_TAGGING_LEVEL_TBI = 1, 326 #define M_HEAP_TAGGING_LEVEL_TBI M_HEAP_TAGGING_LEVEL_TBI 327 /** 328 * Enable heap tagging and asynchronous memory tag checks (if supported). 329 * Disable stack trace collection. 330 */ 331 M_HEAP_TAGGING_LEVEL_ASYNC = 2, 332 #define M_HEAP_TAGGING_LEVEL_ASYNC M_HEAP_TAGGING_LEVEL_ASYNC 333 /** 334 * Enable heap tagging and synchronous memory tag checks (if supported). 335 * Enable stack trace collection. 336 */ 337 M_HEAP_TAGGING_LEVEL_SYNC = 3, 338 #define M_HEAP_TAGGING_LEVEL_SYNC M_HEAP_TAGGING_LEVEL_SYNC 339 }; 340 341 /** 342 * mallopt() option to print human readable statistics about the memory 343 * allocator to the log. There is no format for this data, each allocator 344 * can use a different format, and the data that is printed can 345 * change at any time. This is expected to be used as a debugging aid. 346 * 347 * Available since API level 35. 348 */ 349 #define M_LOG_STATS (-205) 350 351 /** 352 * [mallopt(3)](http://man7.org/linux/man-pages/man3/mallopt.3.html) modifies 353 * heap behavior. Values of `__option` are the `M_` constants from this header. 354 * 355 * Returns 1 on success, 0 on error. 356 * 357 * Available since API level 26. 358 */ 359 int mallopt(int __option, int __value) __INTRODUCED_IN(26); 360 361 /** 362 * [__malloc_hook(3)](http://man7.org/linux/man-pages/man3/__malloc_hook.3.html) 363 * is called to implement malloc(). By default this points to the system's 364 * implementation. 365 * 366 * Available since API level 28. 367 * 368 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md) 369 */ 370 extern void* _Nonnull (*volatile _Nonnull __malloc_hook)(size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28); 371 372 /** 373 * [__realloc_hook(3)](http://man7.org/linux/man-pages/man3/__realloc_hook.3.html) 374 * is called to implement realloc(). By default this points to the system's 375 * implementation. 376 * 377 * Available since API level 28. 378 * 379 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md) 380 */ 381 extern void* _Nonnull (*volatile _Nonnull __realloc_hook)(void* _Nullable __ptr, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28); 382 383 /** 384 * [__free_hook(3)](http://man7.org/linux/man-pages/man3/__free_hook.3.html) 385 * is called to implement free(). By default this points to the system's 386 * implementation. 387 * 388 * Available since API level 28. 389 * 390 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/main/libc/malloc_hooks/README.md) 391 */ 392 extern void (*volatile _Nonnull __free_hook)(void* _Nullable __ptr, const void* _Nonnull __caller) __INTRODUCED_IN(28); 393 394 /** 395 * [__memalign_hook(3)](http://man7.org/linux/man-pages/man3/__memalign_hook.3.html) 396 * is called to implement memalign(). 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 __memalign_hook)(size_t __alignment, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28); 404 405 __END_DECLS 406