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