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* 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* 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* realloc(void* __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 void* reallocarray(void* __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) __wur __INTRODUCED_IN(29); 74 75 /** 76 * [free(3)](http://man7.org/linux/man-pages/man3/free.3.html) deallocates 77 * memory on the heap. 78 */ 79 void free(void* __ptr); 80 81 /** 82 * [memalign(3)](http://man7.org/linux/man-pages/man3/memalign.3.html) allocates 83 * memory on the heap with the required alignment. 84 * 85 * Returns a pointer to the allocated memory on success and returns a null 86 * pointer and sets `errno` on failure. 87 * 88 * See also posix_memalign(). 89 */ 90 void* memalign(size_t __alignment, size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(2) __wur; 91 92 /** 93 * [malloc_usable_size(3)](http://man7.org/linux/man-pages/man3/malloc_usable_size.3.html) 94 * returns the actual size of the given heap block. 95 * 96 * Available since API level 17. 97 */ 98 size_t malloc_usable_size(const void* __ptr) __INTRODUCED_IN(17); 99 100 #ifndef STRUCT_MALLINFO_DECLARED 101 #define STRUCT_MALLINFO_DECLARED 1 102 struct mallinfo { 103 /** Total number of non-mmapped bytes currently allocated from OS. */ 104 size_t arena; 105 /** Number of free chunks. */ 106 size_t ordblks; 107 /** (Unused.) */ 108 size_t smblks; 109 /** (Unused.) */ 110 size_t hblks; 111 /** Total number of bytes in mmapped regions. */ 112 size_t hblkhd; 113 /** Maximum total allocated space; greater than total if trimming has occurred. */ 114 size_t usmblks; 115 /** (Unused.) */ 116 size_t fsmblks; 117 /** Total allocated space (normal or mmapped.) */ 118 size_t uordblks; 119 /** Total free space. */ 120 size_t fordblks; 121 /** Upper bound on number of bytes releasable by a trim operation. */ 122 size_t keepcost; 123 }; 124 #endif 125 126 /** 127 * [mallinfo(3)](http://man7.org/linux/man-pages/man3/mallinfo.3.html) returns 128 * information about the current state of the heap. Note that mallinfo() is 129 * inherently unreliable and consider using malloc_info() instead. 130 */ 131 struct mallinfo mallinfo(void); 132 133 /** 134 * [malloc_info(3)](http://man7.org/linux/man-pages/man3/malloc_info.3.html) 135 * writes information about the current state of the heap to the given stream. 136 * 137 * The XML structure for malloc_info() is as follows: 138 * ``` 139 * <malloc version="jemalloc-1"> 140 * <heap nr="INT"> 141 * <allocated-large>INT</allocated-large> 142 * <allocated-huge>INT</allocated-huge> 143 * <allocated-bins>INT</allocated-bins> 144 * <bins-total>INT</bins-total> 145 * <bin nr="INT"> 146 * <allocated>INT</allocated> 147 * <nmalloc>INT</nmalloc> 148 * <ndalloc>INT</ndalloc> 149 * </bin> 150 * <!-- more bins --> 151 * </heap> 152 * <!-- more heaps --> 153 * </malloc> 154 * ``` 155 * 156 * Available since API level 23. 157 */ 158 int malloc_info(int __must_be_zero, FILE* __fp) __INTRODUCED_IN(23); 159 160 /** 161 * mallopt() option to set the decay time. Valid values are 0 and 1. 162 * 163 * Available since API level 27. 164 */ 165 #define M_DECAY_TIME (-100) 166 /** 167 * mallopt() option to immediately purge any memory not in use. This 168 * will release the memory back to the kernel. The value is ignored. 169 * 170 * Available since API level 28. 171 */ 172 #define M_PURGE (-101) 173 /** 174 * mallopt() option to set the maximum number of items in the secondary 175 * cache of the scudo allocator. 176 * 177 * Available since API level 31. 178 */ 179 #define M_CACHE_COUNT_MAX (-200) 180 /** 181 * mallopt() option to set the maximum size in bytes of a cacheable item in 182 * the secondary cache of the scudo allocator. 183 * 184 * Available since API level 31. 185 */ 186 #define M_CACHE_SIZE_MAX (-201) 187 /** 188 * mallopt() option to increase the maximum number of shared thread-specific 189 * data structures that can be created. This number cannot be decreased, 190 * only increased and only applies to the scudo allocator. 191 * 192 * Available since API level 31. 193 */ 194 #define M_TSDS_COUNT_MAX (-202) 195 196 /** 197 * [mallopt(3)](http://man7.org/linux/man-pages/man3/mallopt.3.html) modifies 198 * heap behavior. Values of `__option` are the `M_` constants from this header. 199 * 200 * Returns 1 on success, 0 on error. 201 * 202 * Available since API level 26. 203 */ 204 int mallopt(int __option, int __value) __INTRODUCED_IN(26); 205 206 /** 207 * [__malloc_hook(3)](http://man7.org/linux/man-pages/man3/__malloc_hook.3.html) 208 * is called to implement malloc(). By default this points to the system's 209 * implementation. 210 * 211 * Available since API level 28. 212 * 213 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md) 214 */ 215 extern void* (*volatile __malloc_hook)(size_t __byte_count, const void* __caller) __INTRODUCED_IN(28); 216 217 /** 218 * [__realloc_hook(3)](http://man7.org/linux/man-pages/man3/__realloc_hook.3.html) 219 * is called to implement realloc(). By default this points to the system's 220 * implementation. 221 * 222 * Available since API level 28. 223 * 224 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md) 225 */ 226 extern void* (*volatile __realloc_hook)(void* __ptr, size_t __byte_count, const void* __caller) __INTRODUCED_IN(28); 227 228 /** 229 * [__free_hook(3)](http://man7.org/linux/man-pages/man3/__free_hook.3.html) 230 * is called to implement free(). By default this points to the system's 231 * implementation. 232 * 233 * Available since API level 28. 234 * 235 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md) 236 */ 237 extern void (*volatile __free_hook)(void* __ptr, const void* __caller) __INTRODUCED_IN(28); 238 239 /** 240 * [__memalign_hook(3)](http://man7.org/linux/man-pages/man3/__memalign_hook.3.html) 241 * is called to implement memalign(). By default this points to the system's 242 * implementation. 243 * 244 * Available since API level 28. 245 * 246 * See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md) 247 */ 248 extern void* (*volatile __memalign_hook)(size_t __alignment, size_t __byte_count, const void* __caller) __INTRODUCED_IN(28); 249 250 __END_DECLS 251