1/*
2 * Copyright (c) 1999-2023 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 <TargetConditionals.h>
28#include <malloc/_platform.h>
29#include <Availability.h>
30#include <os/availability.h>
31
32#include <malloc/_ptrcheck.h>
33__ptrcheck_abi_assume_single()
34
35#if __has_feature(ptrauth_calls)
36#include <ptrauth.h>
37
38// Zone function pointer, type-diversified but not address-diversified (because
39// the zone can be copied). Process-independent because the zone structure may
40// be in the shared library cache.
41#define MALLOC_ZONE_FN_PTR(fn) __ptrauth(ptrauth_key_process_independent_code, \
42 0, ptrauth_string_discriminator("malloc_zone_fn." #fn)) fn
43
44// Introspection function pointer, address- and type-diversified.
45// Process-independent because the malloc_introspection_t structure that contains
46// these pointers may be in the shared library cache.
47#define MALLOC_INTROSPECT_FN_PTR(fn) __ptrauth(ptrauth_key_process_independent_code, \
48 1, ptrauth_string_discriminator("malloc_introspect_fn." #fn)) fn
49
50// Pointer to the introspection pointer table, type-diversified but not
51// address-diversified (because the zone can be copied).
52// Process-independent because the table pointer may be in the shared library cache.
53#define MALLOC_INTROSPECT_TBL_PTR(ptr) __ptrauth(ptrauth_key_process_independent_data,\
54 0, ptrauth_string_discriminator("malloc_introspect_tbl")) ptr
55
56#endif // __has_feature(ptrauth_calls)
57
58#ifndef MALLOC_ZONE_FN_PTR
59#define MALLOC_ZONE_FN_PTR(fn) fn
60#define MALLOC_INTROSPECT_FN_PTR(fn) fn
61#define MALLOC_INTROSPECT_TBL_PTR(ptr) ptr
62#endif // MALLOC_ZONE_FN_PTR
63
64__BEGIN_DECLS
65
66/********* Typed zone functions ************/
67
68#if defined(__has_attribute) && __has_attribute(swift_name)
69#define MALLOC_SWIFT_NAME(x) __attribute__((swift_name(#x)))
70#else
71#define MALLOC_SWIFT_NAME(x)
72#endif // defined(__has_attribute) && __has_attribute(swift_name)
73
74/*!
75 * @constant MALLOC_ZONE_MALLOC_DEFAULT_ALIGN
76 * Default alignment for malloc_type_zone_malloc_with_options
77 */
78#define MALLOC_ZONE_MALLOC_DEFAULT_ALIGN __SIZEOF_POINTER__
79
80/*!
81 * @enum malloc_zone_malloc_options_t
82 *
83 * @constant MALLOC_ZONE_MALLOC_OPTION_NONE
84 * Empty placeholder option.
85 *
86 * @constant MALLOC_ZONE_MALLOC_OPTION_CLEAR
87 * Zero out the allocated memory, similar to calloc().
88 *
89 * @constant MALLOC_ZONE_MALLOC_OPTION_CANONICAL_TAG
90 * Under MTE, use a tag of zero (canonical) instead of a random value.
91 */
92typedef enum __enum_options : uint64_t {
93 MALLOC_ZONE_MALLOC_OPTION_NONE = 0u,
94 MALLOC_ZONE_MALLOC_OPTION_CLEAR MALLOC_SWIFT_NAME(clear) = 1u << 0,
95 MALLOC_ZONE_MALLOC_OPTION_CANONICAL_TAG MALLOC_SWIFT_NAME(canonicalTag) = 1u << 1,
96} malloc_zone_malloc_options_t;
97
98/*!
99 * @function malloc_type_zone_malloc_with_options
100 *
101 * Like the other functions declared in malloc/_malloc_type.h, this function
102 * is not intended to be called directly, but is rather the rewrite target for
103 * calls to malloc_zone_malloc_with_options when typed memory operations are
104 * enabled.
105 */
106#if defined(__LP64__)
107__API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0), visionos(26.0), driverkit(25.0))
108void * __sized_by_or_null(size) malloc_type_zone_malloc_with_options(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id, malloc_zone_malloc_options_t opts) __result_use_check __alloc_align(2) __alloc_size(3);
109#endif /* __LP64__ */
110
111#if defined(_MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING) && _MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING
112static void * __sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_malloc_with_options_backdeploy(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id, malloc_zone_malloc_options_t opts) __result_use_check __alloc_align(2) __alloc_size(3);
113#endif /* defined(_MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING) && _MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING */
114
115// The remainder of these functions are declared in malloc/_malloc_type.h, and
116// the backdeployment variant definitions are at the bottom of this file.
117
118/********* Type definitions ************/
119
120/*
121 * Only zone implementors should depend on the layout of this structure;
122 * Regular callers should use the access functions below
123 */
124typedef struct _malloc_zone_t {
125 void *reserved1; /* RESERVED FOR CFAllocator DO NOT USE */
126 void *reserved2; /* RESERVED FOR CFAllocator DO NOT USE */
127
128 /*
129 * Returns the size of a block or 0 if not in this zone; must be fast,
130 * especially for negative answers.
131 */
132 size_t (* MALLOC_ZONE_FN_PTR(size))(struct _malloc_zone_t *zone,
133 const void * __unsafe_indexable ptr);
134
135 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc))(
136 struct _malloc_zone_t *zone, size_t size);
137
138 /* Same as malloc, but block returned is set to zero */
139 void * __sized_by_or_null(num_items * size) (* MALLOC_ZONE_FN_PTR(calloc))(
140 struct _malloc_zone_t *zone, size_t num_items, size_t size);
141
142 /* Same as malloc, but block returned is guaranteed to be page-aligned */
143 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(valloc))(
144 struct _malloc_zone_t *zone, size_t size);
145
146 void (* MALLOC_ZONE_FN_PTR(free))(struct _malloc_zone_t *zone,
147 void * __unsafe_indexable ptr);
148
149 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(realloc))(
150 struct _malloc_zone_t *zone, void * __unsafe_indexable ptr,
151 size_t size);
152
153 /* Zone is destroyed and all memory reclaimed */
154 void (* MALLOC_ZONE_FN_PTR(destroy))(struct _malloc_zone_t *zone);
155
156 const char * __null_terminated zone_name;
157
158 /* Optional batch callbacks; these may be NULL */
159
160 /*
161 * Given a size, returns pointers capable of holding that size; returns the
162 * number of pointers allocated (maybe 0 or less than num_requested)
163 */
164 unsigned (* MALLOC_ZONE_FN_PTR(batch_malloc))(struct _malloc_zone_t *zone,
165 size_t size,
166 void * __unsafe_indexable * __counted_by(num_requested) results,
167 unsigned num_requested);
168
169 /*
170 * Frees all the pointers in to_be_freed; note that to_be_freed may be
171 * overwritten during the process
172 */
173 void (* MALLOC_ZONE_FN_PTR(batch_free))(struct _malloc_zone_t *zone,
174 void * __unsafe_indexable * __counted_by(num_to_be_freed) to_be_freed,
175 unsigned num_to_be_freed);
176
177 struct malloc_introspection_t * MALLOC_INTROSPECT_TBL_PTR(introspect);
178 unsigned version;
179
180 /* Aligned memory allocation. May be NULL. Present in version >= 5. */
181 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(memalign))(
182 struct _malloc_zone_t *zone, size_t alignment, size_t size);
183
184 /*
185 * Free a pointer known to be in zone and known to have the given size.
186 * May be NULL. Present in version >= 6.
187 */
188 void (* MALLOC_ZONE_FN_PTR(free_definite_size))(struct _malloc_zone_t *zone,
189 void * __sized_by(size) ptr, size_t size);
190
191 /*
192 * Empty out caches in the face of memory pressure. May be NULL.
193 * Present in version >= 8.
194 */
195 size_t (* MALLOC_ZONE_FN_PTR(pressure_relief))(struct _malloc_zone_t *zone,
196 size_t goal);
197
198 /*
199 * Checks whether an address might belong to the zone. May be NULL. Present
200 * in version >= 10. False positives are allowed (e.g. the pointer was
201 * freed, or it's in zone space that has not yet been allocated. False
202 * negatives are not allowed.
203 */
204 boolean_t (* MALLOC_ZONE_FN_PTR(claimed_address))(
205 struct _malloc_zone_t *zone, void * __unsafe_indexable ptr);
206
207 /*
208 * For libmalloc-internal zone 0 implementations only: try to free ptr,
209 * promising to call find_zone_and_free if it turns out not to belong to us.
210 * May be present in version >= 13.
211 */
212 void (* MALLOC_ZONE_FN_PTR(try_free_default))(struct _malloc_zone_t *zone,
213 void * __unsafe_indexable ptr);
214
215 /*
216 * Memory allocation with an extensible binary flags option.
217 * Added in version >= 15.
218 */
219 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc_with_options))(
220 struct _malloc_zone_t *zone, size_t align, size_t size,
221 uint64_t options);
222
223 /*
224 * Typed Memory Operations versions of zone functions. Present in
225 * version >= 16.
226 */
227
228 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc_type_malloc))(
229 struct _malloc_zone_t *zone, size_t size, malloc_type_id_t type_id);
230
231 void * __sized_by_or_null(count * size) (* MALLOC_ZONE_FN_PTR(malloc_type_calloc))(
232 struct _malloc_zone_t *zone, size_t count, size_t size,
233 malloc_type_id_t type_id);
234
235 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc_type_realloc))(
236 struct _malloc_zone_t *zone, void * __unsafe_indexable ptr,
237 size_t size, malloc_type_id_t type_id);
238
239 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc_type_memalign))(
240 struct _malloc_zone_t *zone, size_t alignment, size_t size,
241 malloc_type_id_t type_id);
242
243 void * __sized_by_or_null(size) (* MALLOC_ZONE_FN_PTR(malloc_type_malloc_with_options))(
244 struct _malloc_zone_t *zone, size_t align, size_t size,
245 uint64_t options, malloc_type_id_t type_id);
246} malloc_zone_t;
247
248/*!
249 * @enum malloc_type_callsite_flags_v0_t
250 *
251 * Information about where and how malloc was called
252 *
253 * @constant MALLOC_TYPE_CALLSITE_FLAGS_V0_FIXED_SIZE
254 * Set in malloc_type_summary_v0_t if the call to malloc was called with a fixed
255 * size. Note that, at present, this bit is set in all callsites where the
256 * compiler rewrites a call to malloc
257 *
258 * @constant MALLOC_TYPE_CALLSITE_FLAGS_V0_ARRAY
259 * Set in malloc_type_summary_v0_t if the type being allocated is an array, e.g.
260 * allocated via new[] or calloc(count, size)
261 */
262typedef enum {
263 MALLOC_TYPE_CALLSITE_FLAGS_V0_NONE = 0,
264 MALLOC_TYPE_CALLSITE_FLAGS_V0_FIXED_SIZE = 1 << 0,
265 MALLOC_TYPE_CALLSITE_FLAGS_V0_ARRAY = 1 << 1,
266} malloc_type_callsite_flags_v0_t;
267
268/*!
269 * @enum malloc_type_kind_v0_t
270 *
271 * @constant MALLOC_TYPE_KIND_V0_OTHER
272 * Default allocation type, used for most calls to malloc
273 *
274 * @constant MALLOC_TYPE_KIND_V0_OBJC
275 * Marks a type allocated by libobjc
276 *
277 * @constant MALLOC_TYPE_KIND_V0_SWIFT
278 * Marks a type allocated by the Swift runtime
279 *
280 * @constant MALLOC_TYPE_KIND_V0_CXX
281 * Marks a type allocated by the C++ runtime's operator new
282 */
283typedef enum {
284 MALLOC_TYPE_KIND_V0_OTHER = 0,
285 MALLOC_TYPE_KIND_V0_OBJC = 1,
286 MALLOC_TYPE_KIND_V0_SWIFT = 2,
287 MALLOC_TYPE_KIND_V0_CXX = 3
288} malloc_type_kind_v0_t;
289
290/*!
291 * @struct malloc_type_layout_semantics_v0_t
292 *
293 * @field contains_data_pointer
294 * True if the allocated type or any of its fields is a pointer
295 * to a data type (i.e. the pointee contains no pointers)
296 *
297 * @field contains_struct_pointer
298 * True if the allocated type or any of its fields is a pointer
299 * to a struct or union
300 *
301 * @field contains_immutable_pointer
302 * True if the allocated type or any of its fields is a const pointer
303 *
304 * @field contains_anonymous_pointer
305 * True if the allocated type or any of its fields is a pointer
306 * to something other than a struct or data type
307 *
308 * @field is_reference_counted
309 * True if the allocated type is reference counted
310 *
311 * @field contains_generic_data
312 * True if the allocated type or any of its fields are not pointers
313 */
314typedef struct {
315 bool contains_data_pointer : 1;
316 bool contains_struct_pointer : 1;
317 bool contains_immutable_pointer : 1;
318 bool contains_anonymous_pointer : 1;
319 bool is_reference_counted : 1;
320 uint16_t reserved_0 : 3;
321 bool contains_generic_data : 1;
322 uint16_t reserved_1 : 7;
323} malloc_type_layout_semantics_v0_t;
324
325/*!
326 * @struct malloc_type_summary_v0_t
327 *
328 * @field version
329 * Versioning field of the type summary. Set to 0 for the current verison. New
330 * fields can be added where the reserved fields currently are without
331 * incrementing the version, as long as they are non-breaking.
332 *
333 * @field callsite_flags
334 * Details from the callsite of malloc inferred by the compiler
335 *
336 * @field type_kind
337 * Details about the runtime making the allocation
338 *
339 * @field layout_semantics
340 * Details about what kinds of data are contained in the type being allocated
341 *
342 * @discussion
343 * The reserved fields should not be read from or written to, and may be
344 * used for additional fields and information in future versions
345 */
346typedef struct {
347 uint32_t version : 4;
348 uint32_t reserved_0 : 2;
349 malloc_type_callsite_flags_v0_t callsite_flags : 4;
350 malloc_type_kind_v0_t type_kind : 2;
351 uint32_t reserved_1 : 4;
352 malloc_type_layout_semantics_v0_t layout_semantics;
353} malloc_type_summary_v0_t;
354
355/*!
356 * @union malloc_type_descriptor_v0_t
357 *
358 * @field hash
359 * Hash of the type layout of the allocated type, or if type inference failed,
360 * the hash of the callsite's file, line and column. The hash allows the
361 * allocator to disambiguate between different types with the same summary, e.g.
362 * types that have the same fields in different orders.
363 *
364 * @field summary
365 * Details of the type being allocated
366 *
367 * @field type_id
368 * opaque type used for punning
369 *
370 * @discussion
371 * Use malloc_type_descriptor_v0_t to decode the opaque malloc_type_id_t with
372 * version == 0 into a malloc_type_summary_v0_t:
373 *
374 * <code>
375 * malloc_type_descriptor_v0_t desc = (malloc_type_descriptor_v0_t){ .type_id = id };
376 * </code>
377 *
378 * See LLVM documentation for more details
379 */
380typedef union {
381 struct {
382 uint32_t hash;
383 malloc_type_summary_v0_t summary;
384 };
385 malloc_type_id_t type_id;
386} malloc_type_descriptor_v0_t;
387
388/********* Creation and destruction ************/
389
390extern malloc_zone_t *malloc_default_zone(void);
391 /* The initial zone */
392
393#if !0 && !0
394extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags);
395 /* Creates a new zone with default behavior and registers it */
396
397extern void malloc_destroy_zone(malloc_zone_t *zone);
398 /* Destroys zone and everything it allocated */
399#endif
400
401/********* Block creation and manipulation ************/
402
403extern void * __sized_by_or_null(size) malloc_zone_malloc(malloc_zone_t *zone, size_t size) __alloc_size(2) _MALLOC_TYPED(malloc_type_zone_malloc, 2);
404 /* Allocates a new pointer of size size; zone must be non-NULL */
405
406/*!
407 * @function malloc_zone_malloc_with_options
408 *
409 * @param zone
410 * The malloc zone that should be used to used to serve the allocation. This
411 * parameter may be NULL, in which case the default zone will be used.
412 *
413 * @param align
414 * The minimum alignment of the requested allocation. This non-zero parameter
415 * must be MALLOC_ZONE_MALLOC_DEFAULT_ALIGN to request default alignment, or a
416 * power of 2 > sizeof(void *).
417 *
418 * @param size
419 * The size, in bytes, of the requested allocation, which must be an integral
420 * multiple of align. This requirement is relaxed slightly on OS versions
421 * strictly newer than 26.0, where a non-multiple size is permitted if and only
422 * if align is MALLOC_ZONE_MALLOC_DEFAULT_ALIGN. OS version 26.0 does not
423 * implement this exception.
424 *
425 * @param options
426 * A bitmask of options defining how the memory should be allocated. See the
427 * available bit values in the malloc_zone_malloc_options_t enum definition.
428 *
429 * @result
430 * A pointer to the newly allocated block of memory, or NULL if the allocation
431 * failed.
432 *
433 * @discussion
434 * This API does not use errno to signal information about the reason for its
435 * success or failure, and makes no guarantees about preserving or settings its
436 * value in any case.
437 */
438__API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), watchos(26.0), visionos(26.0), driverkit(25.0))
439extern void * __sized_by_or_null(size) malloc_zone_malloc_with_options(malloc_zone_t *zone, size_t align, size_t size, malloc_zone_malloc_options_t opts) __alloc_align(2) __alloc_size(3) _MALLOC_TYPED(malloc_type_zone_malloc_with_options, 3);
440
441extern void * __sized_by_or_null(num_items * size) malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size) __alloc_size(2,3) _MALLOC_TYPED(malloc_type_zone_calloc, 3);
442 /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */
443
444extern void * __sized_by_or_null(size) malloc_zone_valloc(malloc_zone_t *zone, size_t size) __alloc_size(2) _MALLOC_TYPED(malloc_type_zone_valloc, 2);
445 /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */
446
447extern void malloc_zone_free(malloc_zone_t *zone, void * __unsafe_indexable ptr);
448 /* Frees pointer in zone; zone must be non-NULL */
449
450extern void * __sized_by_or_null(size) malloc_zone_realloc(malloc_zone_t *zone, void * __unsafe_indexable ptr, size_t size) __alloc_size(3) _MALLOC_TYPED(malloc_type_zone_realloc, 3);
451 /* Enlarges block if necessary; zone must be non-NULL */
452
453extern malloc_zone_t *malloc_zone_from_ptr(const void * __unsafe_indexable ptr);
454 /* Returns the zone for a pointer, or NULL if not in any zone.
455 The ptr must have been returned from a malloc or realloc call. */
456
457extern size_t malloc_size(const void * __unsafe_indexable ptr);
458 /* Returns size of given ptr, including any padding inserted by the allocator */
459
460extern size_t malloc_good_size(size_t size);
461 /* Returns number of bytes greater than or equal to size that can be allocated without padding */
462
463extern void * __sized_by_or_null(size) malloc_zone_memalign(malloc_zone_t *zone, size_t alignment, size_t size) __alloc_align(2) __alloc_size(3) _MALLOC_TYPED(malloc_type_zone_memalign, 3) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
464 /*
465 * Allocates a new pointer of size size whose address is an exact multiple of alignment.
466 * alignment must be a power of two and at least as large as sizeof(void *).
467 * zone must be non-NULL.
468 */
469
470/********* Batch methods ************/
471
472#if !0 && !0
473extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void * __unsafe_indexable * __counted_by(num_requested) results, unsigned num_requested);
474 /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */
475
476extern void malloc_zone_batch_free(malloc_zone_t *zone, void * __unsafe_indexable * __counted_by(num) to_be_freed, unsigned num);
477 /* 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 */
478#endif
479
480/********* Functions for libcache ************/
481
482#if !0 && !0
483extern malloc_zone_t *malloc_default_purgeable_zone(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
484 /* Returns a pointer to the default purgeable_zone. */
485
486extern void malloc_make_purgeable(void * __unsafe_indexable ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
487 /* Make an allocation from the purgeable zone purgeable if possible. */
488
489extern int malloc_make_nonpurgeable(void * __unsafe_indexable ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
490 /* Makes an allocation from the purgeable zone nonpurgeable.
491 * Returns zero if the contents were not purged since the last
492 * call to malloc_make_purgeable, else returns non-zero. */
493#endif
494
495/********* Functions for zone implementors ************/
496
497#if !0 && !0
498extern void malloc_zone_register(malloc_zone_t *zone);
499 /* Registers a custom malloc zone; Should typically be called after a
500 * malloc_zone_t has been filled in with custom methods by a client. See
501 * malloc_create_zone for creating additional malloc zones with the
502 * default allocation and free behavior. */
503
504extern void malloc_zone_unregister(malloc_zone_t *zone);
505 /* De-registers a zone
506 Should typically be called before calling the zone destruction routine */
507#endif
508
509extern void malloc_set_zone_name(malloc_zone_t *zone, const char * __null_terminated name);
510 /* Sets the name of a zone */
511
512extern const char *malloc_get_zone_name(malloc_zone_t *zone);
513 /* Returns the name of a zone */
514
515#if !0 && !0
516size_t malloc_zone_pressure_relief(malloc_zone_t *zone, size_t goal) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
517 /* malloc_zone_pressure_relief() advises the malloc subsystem that the process is under memory pressure and
518 * that the subsystem should make its best effort towards releasing (i.e. munmap()-ing) "goal" bytes from "zone".
519 * If "goal" is passed as zero, the malloc subsystem will attempt to achieve maximal pressure relief in "zone".
520 * If "zone" is passed as NULL, all zones are examined for pressure relief opportunities.
521 * malloc_zone_pressure_relief() returns the number of bytes released.
522 */
523#endif
524
525typedef struct {
526 vm_address_t address;
527 vm_size_t size;
528} vm_range_t;
529
530typedef struct malloc_statistics_t {
531 unsigned blocks_in_use;
532 size_t size_in_use;
533 size_t max_size_in_use; /* high water mark of touched memory */
534 size_t size_allocated; /* reserved in memory */
535} malloc_statistics_t;
536
537typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void * __sized_by(size) *local_memory);
538 /* given a task, "reads" the memory at the given address and size
539 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */
540
541#define MALLOC_PTR_IN_USE_RANGE_TYPE 1 /* for allocated pointers */
542#define MALLOC_PTR_REGION_RANGE_TYPE 2 /* for region containing pointers */
543#define MALLOC_ADMIN_REGION_RANGE_TYPE 4 /* for region used internally */
544#define MALLOC_ZONE_SPECIFIC_FLAGS 0xff00 /* bits reserved for zone-specific purposes */
545
546typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);
547/* given a task and context, "records" the specified addresses */
548
549/* Print function for the print_task() operation. */
550typedef void print_task_printer_t(const char * __null_terminated fmt, ...) __printflike(1,2);
551
552typedef struct malloc_introspection_t {
553 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 */
554 size_t (* MALLOC_INTROSPECT_FN_PTR(good_size))(malloc_zone_t *zone, size_t size);
555 boolean_t (* MALLOC_INTROSPECT_FN_PTR(check))(malloc_zone_t *zone); /* Consistency checker */
556 void (* MALLOC_INTROSPECT_FN_PTR(print))(malloc_zone_t *zone, boolean_t verbose); /* Prints zone */
557 void (* MALLOC_INTROSPECT_FN_PTR(log))(malloc_zone_t *zone, void * __unsafe_indexable address); /* Enables logging of activity */
558 void (* MALLOC_INTROSPECT_FN_PTR(force_lock))(malloc_zone_t *zone); /* Forces locking zone */
559 void (* MALLOC_INTROSPECT_FN_PTR(force_unlock))(malloc_zone_t *zone); /* Forces unlocking zone */
560 void (* MALLOC_INTROSPECT_FN_PTR(statistics))(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */
561 boolean_t (* MALLOC_INTROSPECT_FN_PTR(zone_locked))(malloc_zone_t *zone); /* Are any zone locks held */
562
563 /* Discharge checking. Present in version >= 7. */
564 boolean_t (* MALLOC_INTROSPECT_FN_PTR(enable_discharge_checking))(malloc_zone_t *zone);
565 void (* MALLOC_INTROSPECT_FN_PTR(disable_discharge_checking))(malloc_zone_t *zone);
566 void (* MALLOC_INTROSPECT_FN_PTR(discharge))(malloc_zone_t *zone, void * __unsafe_indexable memory);
567#ifdef __BLOCKS__
568 void (* MALLOC_INTROSPECT_FN_PTR(enumerate_discharged_pointers))(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info));
569 #else
570 void *enumerate_unavailable_without_blocks;
571#endif /* __BLOCKS__ */
572 void (* MALLOC_INTROSPECT_FN_PTR(reinit_lock))(malloc_zone_t *zone); /* Reinitialize zone locks, called only from atfork_child handler. Present in version >= 9. */
573 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. */
574 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. */
575 unsigned zone_type; /* Identifies the zone type. 0 means unknown/undefined zone type. Present in version >= 14. */
576} malloc_introspection_t;
577
578// The value of "level" when passed to print_task() that corresponds to
579// verbose passed to print()
580#define MALLOC_VERBOSE_PRINT_LEVEL 2
581
582#if !0 && !0
583extern void malloc_printf(const char * __null_terminated format, ...) __printflike(1,2);
584 /* Convenience for logging errors and warnings;
585 No allocation is performed during execution of this function;
586 Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...)
587 */
588#endif
589
590/********* Functions for performance tools ************/
591
592#if !0 && !0
593extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t * __single * __counted_by(*count) addresses, unsigned *count);
594 /* Fills addresses and count with the addresses of the zones in task;
595 Note that the validity of the addresses returned correspond to the validity reader */
596#endif
597
598/********* Debug helpers ************/
599
600extern void malloc_zone_print_ptr_info(void * __unsafe_indexable ptr);
601 /* print to stdout if this pointer is in the malloc heap, free status, and size */
602
603extern boolean_t malloc_zone_check(malloc_zone_t *zone);
604 /* Checks zone is well formed; if !zone, checks all zones */
605
606extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);
607 /* Prints summary on zone; if !zone, prints all zones */
608
609#if !0 && !0
610extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats);
611 /* Fills statistics for zone; if !zone, sums up all zones */
612
613extern void malloc_zone_log(malloc_zone_t *zone, void * __unsafe_indexable address);
614 /* Controls logging of all activity; if !zone, for all zones;
615 If address==0 nothing is logged;
616 If address==-1 all activity is logged;
617 Else only the activity regarding address is logged */
618#endif
619
620struct mstats {
621 size_t bytes_total;
622 size_t chunks_used;
623 size_t bytes_used;
624 size_t chunks_free;
625 size_t bytes_free;
626};
627
628#if !0 && !0
629extern struct mstats mstats(void);
630
631extern boolean_t malloc_zone_enable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
632 /* Increment the discharge checking enabled counter for a zone. Returns true if the zone supports checking, false if it does not. */
633
634extern void malloc_zone_disable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
635/* Decrement the discharge checking enabled counter for a zone. */
636
637extern void malloc_zone_discharge(malloc_zone_t *zone, void * __unsafe_indexable memory) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
638 /* Register memory that the programmer expects to be freed soon.
639 zone may be NULL in which case the zone is determined using malloc_zone_from_ptr().
640 If discharge checking is off for the zone this function is a no-op. */
641#endif
642
643#if !0 && !0
644#ifdef __BLOCKS__
645extern 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);
646 /* Calls report_discharged for each block that was registered using malloc_zone_discharge() but has not yet been freed.
647 info is used to provide zone defined information about the memory block.
648 If zone is NULL then the enumeration covers all zones. */
649#else
650extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void *) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
651#endif /* __BLOCKS__ */
652#endif
653
654/********* Zone version summary ************/
655// Version 0, but optional:
656// malloc_zone_t::batch_malloc
657// malloc_zone_t::batch_free
658// Version 5:
659// malloc_zone_t::memalign
660// Version 6:
661// malloc_zone_t::free_definite_size
662// Version 7:
663// malloc_introspection_t::enable_discharge_checking
664// malloc_introspection_t::disable_discharge_checking
665// malloc_introspection_t::discharge
666// Version 8:
667// malloc_zone_t::pressure_relief
668// Version 9:
669// malloc_introspection_t::reinit_lock
670// Version 10:
671// malloc_zone_t::claimed_address
672// Version 11:
673// malloc_introspection_t::print_task
674// Version 12:
675// malloc_introspection_t::task_statistics
676// Version 13:
677// - malloc_zone_t::malloc and malloc_zone_t::calloc assume responsibility for
678// setting errno to ENOMEM on failure
679// - malloc_zone_t::try_free_default (libmalloc only, NULL otherwise)
680// Version 14:
681// malloc_introspection_t::zone_type (mandatory, should be 0)
682// Version 15:
683// malloc_zone_t::malloc_with_options (optional)
684// Version 16:
685// malloc_zone_t::malloc_type_malloc (mandatory)
686// malloc_zone_t::malloc_type_calloc (mandatory)
687// malloc_zone_t::malloc_type_realloc (mandatory)
688// malloc_zone_t::malloc_type_memalign (mandatory)
689// malloc_zone_t::malloc_type_malloc_with_options (optional)
690
691// Zone functions are optional unless specified otherwise above. Calling a zone
692// function requires two checks:
693// * Check zone version to ensure zone struct is large enough to include the member.
694// * Check that the function pointer is not null.
695
696#if defined(_MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING) && _MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING
697static void * __sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_malloc_backdeploy(malloc_zone_t *zone, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2) {
698 __attribute__((weak_import)) void * __sized_by_or_null(size) malloc_type_zone_malloc(malloc_zone_t *zone, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2);
699 __auto_type func = malloc_zone_malloc;
700 if (malloc_type_zone_malloc) {
701 return malloc_type_zone_malloc(zone, size, type_id);
702 }
703 return func(zone, size);
704}
705
706static void * __sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_malloc_with_options_backdeploy(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id, malloc_zone_malloc_options_t opts) __result_use_check __alloc_align(2) __alloc_size(3) {
707 __attribute__((weak_import)) void * __sized_by_or_null(size) malloc_type_zone_malloc_with_options(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id, malloc_zone_malloc_options_t opts) __result_use_check __alloc_align(2) __alloc_size(3);
708 __auto_type func = malloc_zone_malloc_with_options;
709 if (malloc_type_zone_malloc_with_options) {
710 return malloc_type_zone_malloc_with_options(zone, alignment, size, type_id, opts);
711 }
712 return func(zone, alignment, size, opts);
713}
714
715static void * __sized_by_or_null(count * size) __attribute__((always_inline)) malloc_type_zone_calloc_backdeploy(malloc_zone_t *zone, size_t count, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2,3) {
716 __attribute__((weak_import)) void * __sized_by_or_null(count * size) malloc_type_zone_calloc(malloc_zone_t *zone, size_t count, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2,3);
717 __auto_type func = malloc_zone_calloc;
718 if (malloc_type_zone_calloc) {
719 return malloc_type_zone_calloc(zone, count, size, type_id);
720 }
721 return func(zone, count, size);
722}
723
724static void __attribute__((always_inline)) malloc_type_zone_free_backdeploy(malloc_zone_t *zone, void * __unsafe_indexable ptr, malloc_type_id_t type_id) {
725 __attribute__((weak_import)) void malloc_type_zone_free(malloc_zone_t *zone, void * __unsafe_indexable ptr, malloc_type_id_t type_id);
726 __auto_type func = malloc_zone_free;
727 if (malloc_type_zone_free) {
728 malloc_type_zone_free(zone, ptr, type_id);
729 } else {
730 func(zone, ptr);
731 }
732}
733
734static void * __sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_realloc_backdeploy(malloc_zone_t *zone, void * __unsafe_indexable ptr, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(3) {
735 __auto_type func = malloc_zone_realloc;
736 __attribute__((weak_import)) void * __sized_by_or_null(size) malloc_type_zone_realloc(malloc_zone_t *zone, void * __unsafe_indexable ptr, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(3);
737 if (malloc_type_zone_realloc) {
738 return malloc_type_zone_realloc(zone, ptr, size, type_id);
739 }
740 return func(zone, ptr, size);
741}
742
743static void *__sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_valloc_backdeploy(malloc_zone_t *zone, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2) {
744 __attribute__((weak_import)) void *__sized_by_or_null(size) malloc_type_zone_valloc(malloc_zone_t *zone, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(2);
745 __auto_type func = malloc_zone_valloc;
746 if (malloc_type_zone_valloc) {
747 return malloc_type_zone_valloc(zone, size, type_id);
748 }
749 return func(zone, size);
750}
751
752static void *__sized_by_or_null(size) __attribute__((always_inline)) malloc_type_zone_memalign_backdeploy(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_align(2) __alloc_size(3) {
753 __attribute__((weak_import)) void *__sized_by_or_null(size) malloc_type_zone_memalign(malloc_zone_t *zone, size_t alignment, size_t size, malloc_type_id_t type_id) __result_use_check __alloc_align(2) __alloc_size(3);
754 __auto_type func = malloc_zone_memalign;
755 if (malloc_type_zone_memalign) {
756 return malloc_type_zone_memalign(zone, alignment, size, type_id);
757 }
758 return func(zone, alignment, size);
759}
760#endif // defined(_MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING) && _MALLOC_TYPE_MALLOC_IS_BACKDEPLOYING
761
762__END_DECLS
763
764#endif /* _MALLOC_MALLOC_H_ */