1 /* 2 * Copyright (c) 1999 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24 #ifndef _MALLOC_MALLOC_H_ 25 #define _MALLOC_MALLOC_H_ 26 27 #include <stddef.h> 28 #include <mach/mach_types.h> 29 #include <sys/cdefs.h> 30 #include <Availability.h> 31 32 #if __has_feature(ptrauth_calls) 33 #include <ptrauth.h> 34 35 // Zone function pointer, type-diversified but not address-diversified (because 36 // the zone can be copied). Process-independent because the zone structure may 37 // be in the shared library cache. 38 #define MALLOC_ZONE_FN_PTR(fn) __ptrauth(ptrauth_key_process_independent_code, \ 39 FALSE, ptrauth_string_discriminator("malloc_zone_fn." #fn)) fn 40 41 // Introspection function pointer, address- and type-diversified. 42 // Process-independent because the malloc_introspection_t structure that contains 43 // these pointers may be in the shared library cache. 44 #define MALLOC_INTROSPECT_FN_PTR(fn) __ptrauth(ptrauth_key_process_independent_code, \ 45 TRUE, ptrauth_string_discriminator("malloc_introspect_fn." #fn)) fn 46 47 // Pointer to the introspection pointer table, type-diversified but not 48 // address-diversified (because the zone can be copied). 49 // Process-independent because the table pointer may be in the shared library cache. 50 #define MALLOC_INTROSPECT_TBL_PTR(ptr) __ptrauth(ptrauth_key_process_independent_data,\ 51 FALSE, ptrauth_string_discriminator("malloc_introspect_tbl")) ptr 52 53 #endif // __has_feature(ptrauth_calls) 54 55 #ifndef MALLOC_ZONE_FN_PTR 56 #define MALLOC_ZONE_FN_PTR(fn) fn 57 #define MALLOC_INTROSPECT_FN_PTR(fn) fn 58 #define MALLOC_INTROSPECT_TBL_PTR(ptr) ptr 59 #endif // MALLOC_ZONE_FN_PTR 60 61 __BEGIN_DECLS 62 /********* Type definitions ************/ 63 64 typedef struct _malloc_zone_t { 65 /* Only zone implementors should depend on the layout of this structure; 66 Regular callers should use the access functions below */ 67 void *reserved1; /* RESERVED FOR CFAllocator DO NOT USE */ 68 void *reserved2; /* RESERVED FOR CFAllocator DO NOT USE */ 69 size_t (* MALLOC_ZONE_FN_PTR(size))(struct _malloc_zone_t *zone, const void *ptr); /* returns the size of a block or 0 if not in this zone; must be fast, especially for negative answers */ 70 void *(* MALLOC_ZONE_FN_PTR(malloc))(struct _malloc_zone_t *zone, size_t size); 71 void *(* MALLOC_ZONE_FN_PTR(calloc))(struct _malloc_zone_t *zone, size_t num_items, size_t size); /* same as malloc, but block returned is set to zero */ 72 void *(* MALLOC_ZONE_FN_PTR(valloc))(struct _malloc_zone_t *zone, size_t size); /* same as malloc, but block returned is set to zero and is guaranteed to be page aligned */ 73 void (* MALLOC_ZONE_FN_PTR(free))(struct _malloc_zone_t *zone, void *ptr); 74 void *(* MALLOC_ZONE_FN_PTR(realloc))(struct _malloc_zone_t *zone, void *ptr, size_t size); 75 void (* MALLOC_ZONE_FN_PTR(destroy))(struct _malloc_zone_t *zone); /* zone is destroyed and all memory reclaimed */ 76 const char *zone_name; 77 78 /* Optional batch callbacks; these may be NULL */ 79 unsigned (* MALLOC_ZONE_FN_PTR(batch_malloc))(struct _malloc_zone_t *zone, size_t size, void **results, unsigned num_requested); /* given a size, returns pointers capable of holding that size; returns the number of pointers allocated (maybe 0 or less than num_requested) */ 80 void (* MALLOC_ZONE_FN_PTR(batch_free))(struct _malloc_zone_t *zone, void **to_be_freed, unsigned num_to_be_freed); /* frees all the pointers in to_be_freed; note that to_be_freed may be overwritten during the process */ 81 82 struct malloc_introspection_t * MALLOC_INTROSPECT_TBL_PTR(introspect); 83 unsigned version; 84 85 /* aligned memory allocation. The callback may be NULL. Present in version >= 5. */ 86 void *(* MALLOC_ZONE_FN_PTR(memalign))(struct _malloc_zone_t *zone, size_t alignment, size_t size); 87 88 /* free a pointer known to be in zone and known to have the given size. The callback may be NULL. Present in version >= 6.*/ 89 void (* MALLOC_ZONE_FN_PTR(free_definite_size))(struct _malloc_zone_t *zone, void *ptr, size_t size); 90 91 /* Empty out caches in the face of memory pressure. The callback may be NULL. Present in version >= 8. */ 92 size_t (* MALLOC_ZONE_FN_PTR(pressure_relief))(struct _malloc_zone_t *zone, size_t goal); 93 94 /* 95 * Checks whether an address might belong to the zone. May be NULL. Present in version >= 10. 96 * False positives are allowed (e.g. the pointer was freed, or it's in zone space that has 97 * not yet been allocated. False negatives are not allowed. 98 */ 99 boolean_t (* MALLOC_ZONE_FN_PTR(claimed_address))(struct _malloc_zone_t *zone, void *ptr); 100 } malloc_zone_t; 101 102 /********* Creation and destruction ************/ 103 104 extern malloc_zone_t *malloc_default_zone(void); 105 /* The initial zone */ 106 107 extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags); 108 /* Creates a new zone with default behavior and registers it */ 109 110 extern void malloc_destroy_zone(malloc_zone_t *zone); 111 /* Destroys zone and everything it allocated */ 112 113 /********* Block creation and manipulation ************/ 114 115 extern void *malloc_zone_malloc(malloc_zone_t *zone, size_t size) __alloc_size(2); 116 /* Allocates a new pointer of size size; zone must be non-NULL */ 117 118 extern void *malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size) __alloc_size(2,3); 119 /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */ 120 121 extern void *malloc_zone_valloc(malloc_zone_t *zone, size_t size) __alloc_size(2); 122 /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */ 123 124 extern void malloc_zone_free(malloc_zone_t *zone, void *ptr); 125 /* Frees pointer in zone; zone must be non-NULL */ 126 127 extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size) __alloc_size(3); 128 /* Enlarges block if necessary; zone must be non-NULL */ 129 130 extern malloc_zone_t *malloc_zone_from_ptr(const void *ptr); 131 /* Returns the zone for a pointer, or NULL if not in any zone. 132 The ptr must have been returned from a malloc or realloc call. */ 133 134 extern size_t malloc_size(const void *ptr); 135 /* Returns size of given ptr */ 136 137 extern size_t malloc_good_size(size_t size); 138 /* Returns number of bytes greater than or equal to size that can be allocated without padding */ 139 140 extern void *malloc_zone_memalign(malloc_zone_t *zone, size_t alignment, size_t size) __alloc_size(3) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0); 141 /* 142 * Allocates a new pointer of size size whose address is an exact multiple of alignment. 143 * alignment must be a power of two and at least as large as sizeof(void *). 144 * zone must be non-NULL. 145 */ 146 147 /********* Batch methods ************/ 148 149 extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void **results, unsigned num_requested); 150 /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */ 151 152 extern void malloc_zone_batch_free(malloc_zone_t *zone, void **to_be_freed, unsigned num); 153 /* frees all the pointers in to_be_freed; note that to_be_freed may be overwritten during the process; This function will always free even if the zone has no batch callback */ 154 155 /********* Functions for libcache ************/ 156 157 extern malloc_zone_t *malloc_default_purgeable_zone(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0); 158 /* Returns a pointer to the default purgeable_zone. */ 159 160 extern void malloc_make_purgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0); 161 /* Make an allocation from the purgeable zone purgeable if possible. */ 162 163 extern int malloc_make_nonpurgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0); 164 /* Makes an allocation from the purgeable zone nonpurgeable. 165 * Returns zero if the contents were not purged since the last 166 * call to malloc_make_purgeable, else returns non-zero. */ 167 168 /********* Functions for zone implementors ************/ 169 170 extern void malloc_zone_register(malloc_zone_t *zone); 171 /* Registers a custom malloc zone; Should typically be called after a 172 * malloc_zone_t has been filled in with custom methods by a client. See 173 * malloc_create_zone for creating additional malloc zones with the 174 * default allocation and free behavior. */ 175 176 extern void malloc_zone_unregister(malloc_zone_t *zone); 177 /* De-registers a zone 178 Should typically be called before calling the zone destruction routine */ 179 180 extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name); 181 /* Sets the name of a zone */ 182 183 extern const char *malloc_get_zone_name(malloc_zone_t *zone); 184 /* Returns the name of a zone */ 185 186 size_t malloc_zone_pressure_relief(malloc_zone_t *zone, size_t goal) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 187 /* malloc_zone_pressure_relief() advises the malloc subsystem that the process is under memory pressure and 188 * that the subsystem should make its best effort towards releasing (i.e. munmap()-ing) "goal" bytes from "zone". 189 * If "goal" is passed as zero, the malloc subsystem will attempt to achieve maximal pressure relief in "zone". 190 * If "zone" is passed as NULL, all zones are examined for pressure relief opportunities. 191 * malloc_zone_pressure_relief() returns the number of bytes released. 192 */ 193 194 typedef struct { 195 vm_address_t address; 196 vm_size_t size; 197 } vm_range_t; 198 199 typedef struct malloc_statistics_t { 200 unsigned blocks_in_use; 201 size_t size_in_use; 202 size_t max_size_in_use; /* high water mark of touched memory */ 203 size_t size_allocated; /* reserved in memory */ 204 } malloc_statistics_t; 205 206 typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory); 207 /* given a task, "reads" the memory at the given address and size 208 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */ 209 210 #define MALLOC_PTR_IN_USE_RANGE_TYPE 1 /* for allocated pointers */ 211 #define MALLOC_PTR_REGION_RANGE_TYPE 2 /* for region containing pointers */ 212 #define MALLOC_ADMIN_REGION_RANGE_TYPE 4 /* for region used internally */ 213 #define MALLOC_ZONE_SPECIFIC_FLAGS 0xff00 /* bits reserved for zone-specific purposes */ 214 215 typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned); 216 /* given a task and context, "records" the specified addresses */ 217 218 /* Print function for the print_task() operation. */ 219 typedef void print_task_printer_t(const char *fmt, ...); 220 221 typedef struct malloc_introspection_t { 222 kern_return_t (* MALLOC_INTROSPECT_FN_PTR(enumerator))(task_t task, void *, unsigned type_mask, vm_address_t zone_address, memory_reader_t reader, vm_range_recorder_t recorder); /* enumerates all the malloc pointers in use */ 223 size_t (* MALLOC_INTROSPECT_FN_PTR(good_size))(malloc_zone_t *zone, size_t size); 224 boolean_t (* MALLOC_INTROSPECT_FN_PTR(check))(malloc_zone_t *zone); /* Consistency checker */ 225 void (* MALLOC_INTROSPECT_FN_PTR(print))(malloc_zone_t *zone, boolean_t verbose); /* Prints zone */ 226 void (* MALLOC_INTROSPECT_FN_PTR(log))(malloc_zone_t *zone, void *address); /* Enables logging of activity */ 227 void (* MALLOC_INTROSPECT_FN_PTR(force_lock))(malloc_zone_t *zone); /* Forces locking zone */ 228 void (* MALLOC_INTROSPECT_FN_PTR(force_unlock))(malloc_zone_t *zone); /* Forces unlocking zone */ 229 void (* MALLOC_INTROSPECT_FN_PTR(statistics))(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */ 230 boolean_t (* MALLOC_INTROSPECT_FN_PTR(zone_locked))(malloc_zone_t *zone); /* Are any zone locks held */ 231 232 /* Discharge checking. Present in version >= 7. */ 233 boolean_t (* MALLOC_INTROSPECT_FN_PTR(enable_discharge_checking))(malloc_zone_t *zone); 234 void (* MALLOC_INTROSPECT_FN_PTR(disable_discharge_checking))(malloc_zone_t *zone); 235 void (* MALLOC_INTROSPECT_FN_PTR(discharge))(malloc_zone_t *zone, void *memory); 236 #ifdef __BLOCKS__ 237 void (* MALLOC_INTROSPECT_FN_PTR(enumerate_discharged_pointers))(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info)); 238 #else 239 void *enumerate_unavailable_without_blocks; 240 #endif /* __BLOCKS__ */ 241 void (* MALLOC_INTROSPECT_FN_PTR(reinit_lock))(malloc_zone_t *zone); /* Reinitialize zone locks, called only from atfork_child handler. Present in version >= 9. */ 242 void (* MALLOC_INTROSPECT_FN_PTR(print_task))(task_t task, unsigned level, vm_address_t zone_address, memory_reader_t reader, print_task_printer_t printer); /* debug print for another process. Present in version >= 11. */ 243 void (* MALLOC_INTROSPECT_FN_PTR(task_statistics))(task_t task, vm_address_t zone_address, memory_reader_t reader, malloc_statistics_t *stats); /* Present in version >= 12 */ 244 } malloc_introspection_t; 245 246 // The value of "level" when passed to print_task() that corresponds to 247 // verbose passed to print() 248 #define MALLOC_VERBOSE_PRINT_LEVEL 2 249 250 extern void malloc_printf(const char *format, ...); 251 /* Convenience for logging errors and warnings; 252 No allocation is performed during execution of this function; 253 Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...) 254 */ 255 256 /********* Functions for performance tools ************/ 257 258 extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count); 259 /* Fills addresses and count with the addresses of the zones in task; 260 Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */ 261 262 /********* Debug helpers ************/ 263 264 extern void malloc_zone_print_ptr_info(void *ptr); 265 /* print to stdout if this pointer is in the malloc heap, free status, and size */ 266 267 extern boolean_t malloc_zone_check(malloc_zone_t *zone); 268 /* Checks zone is well formed; if !zone, checks all zones */ 269 270 extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose); 271 /* Prints summary on zone; if !zone, prints all zones */ 272 273 extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats); 274 /* Fills statistics for zone; if !zone, sums up all zones */ 275 276 extern void malloc_zone_log(malloc_zone_t *zone, void *address); 277 /* Controls logging of all activity; if !zone, for all zones; 278 If address==0 nothing is logged; 279 If address==-1 all activity is logged; 280 Else only the activity regarding address is logged */ 281 282 struct mstats { 283 size_t bytes_total; 284 size_t chunks_used; 285 size_t bytes_used; 286 size_t chunks_free; 287 size_t bytes_free; 288 }; 289 290 extern struct mstats mstats(void); 291 292 extern boolean_t malloc_zone_enable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 293 /* Increment the discharge checking enabled counter for a zone. Returns true if the zone supports checking, false if it does not. */ 294 295 extern void malloc_zone_disable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 296 /* Decrement the discharge checking enabled counter for a zone. */ 297 298 extern void malloc_zone_discharge(malloc_zone_t *zone, void *memory) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 299 /* Register memory that the programmer expects to be freed soon. 300 zone may be NULL in which case the zone is determined using malloc_zone_from_ptr(). 301 If discharge checking is off for the zone this function is a no-op. */ 302 303 #ifdef __BLOCKS__ 304 extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info)) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 305 /* Calls report_discharged for each block that was registered using malloc_zone_discharge() but has not yet been freed. 306 info is used to provide zone defined information about the memory block. 307 If zone is NULL then the enumeration covers all zones. */ 308 #else 309 extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void *) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 310 #endif /* __BLOCKS__ */ 311 312 __END_DECLS 313 314 #endif /* _MALLOC_MALLOC_H_ */