0a94e1584e
This comes up now and then, and the different behavior with `adb shell` in particular confuses people. Bug: https://github.com/android/ndk/issues/1897 Test: N/A Change-Id: I757fa6b6277610a139f326563d508fb9009dcb75
401 lines
14 KiB
C
401 lines
14 KiB
C
/*
|
|
* Copyright (C) 2012 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
/**
|
|
* @file malloc.h
|
|
* @brief Heap memory allocation.
|
|
*
|
|
* [Debugging Native Memory Use](https://source.android.com/devices/tech/debug/native-memory)
|
|
* is the canonical source for documentation on Android's heap debugging
|
|
* features.
|
|
*/
|
|
|
|
#include <sys/cdefs.h>
|
|
#include <stddef.h>
|
|
#include <stdio.h>
|
|
|
|
__BEGIN_DECLS
|
|
|
|
#define __BIONIC_ALLOC_SIZE(...) __attribute__((__alloc_size__(__VA_ARGS__)))
|
|
|
|
/**
|
|
* [malloc(3)](http://man7.org/linux/man-pages/man3/malloc.3.html) allocates
|
|
* memory on the heap.
|
|
*
|
|
* Returns a pointer to the allocated memory on success and returns a null
|
|
* pointer and sets `errno` on failure.
|
|
*
|
|
* Note that Android (like most Unix systems) allows "overcommit". This
|
|
* allows processes to allocate more memory than the system has, provided
|
|
* they don't use it all. This works because only "dirty" pages that have
|
|
* been written to actually require physical memory. In practice, this
|
|
* means that it's rare to see memory allocation functions return a null
|
|
* pointer, and that a non-null pointer does not mean that you actually
|
|
* have all of the memory you asked for.
|
|
*
|
|
* Note also that the Linux Out Of Memory (OOM) killer behaves differently
|
|
* for code run via `adb shell`. The assumption is that if you ran
|
|
* something via `adb shell` you're a developer who actually wants the
|
|
* device to do what you're asking it to do _even if_ that means killing
|
|
* other processes. Obviously this is not the case for apps, which will
|
|
* be killed in preference to killing other processes.
|
|
*/
|
|
void* _Nullable malloc(size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(1) __wur;
|
|
|
|
/**
|
|
* [calloc(3)](http://man7.org/linux/man-pages/man3/calloc.3.html) allocates
|
|
* and clears memory on the heap.
|
|
*
|
|
* Returns a pointer to the allocated memory on success and returns a null
|
|
* pointer and sets `errno` on failure (but see the notes for malloc()).
|
|
*/
|
|
void* _Nullable calloc(size_t __item_count, size_t __item_size) __mallocfunc __BIONIC_ALLOC_SIZE(1,2) __wur;
|
|
|
|
/**
|
|
* [realloc(3)](http://man7.org/linux/man-pages/man3/realloc.3.html) resizes
|
|
* allocated memory on the heap.
|
|
*
|
|
* Returns a pointer (which may be different from `__ptr`) to the resized
|
|
* memory on success and returns a null pointer and sets `errno` on failure
|
|
* (but see the notes for malloc()).
|
|
*/
|
|
void* _Nullable realloc(void* _Nullable __ptr, size_t __byte_count) __BIONIC_ALLOC_SIZE(2) __wur;
|
|
|
|
/**
|
|
* [reallocarray(3)](http://man7.org/linux/man-pages/man3/realloc.3.html) resizes
|
|
* allocated memory on the heap.
|
|
*
|
|
* Equivalent to `realloc(__ptr, __item_count * __item_size)` but fails if the
|
|
* multiplication overflows.
|
|
*
|
|
* Returns a pointer (which may be different from `__ptr`) to the resized
|
|
* memory on success and returns a null pointer and sets `errno` on failure
|
|
* (but see the notes for malloc()).
|
|
*/
|
|
void* _Nullable reallocarray(void* _Nullable __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) __wur __INTRODUCED_IN(29);
|
|
|
|
/**
|
|
* [free(3)](http://man7.org/linux/man-pages/man3/free.3.html) deallocates
|
|
* memory on the heap.
|
|
*/
|
|
void free(void* _Nullable __ptr);
|
|
|
|
/**
|
|
* [memalign(3)](http://man7.org/linux/man-pages/man3/memalign.3.html) allocates
|
|
* memory on the heap with the required alignment.
|
|
*
|
|
* Returns a pointer to the allocated memory on success and returns a null
|
|
* pointer and sets `errno` on failure (but see the notes for malloc()).
|
|
*
|
|
* See also posix_memalign().
|
|
*/
|
|
void* _Nullable memalign(size_t __alignment, size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(2) __wur;
|
|
|
|
/**
|
|
* [malloc_usable_size(3)](http://man7.org/linux/man-pages/man3/malloc_usable_size.3.html)
|
|
* returns the actual size of the given heap block.
|
|
*/
|
|
size_t malloc_usable_size(const void* _Nullable __ptr);
|
|
|
|
#define __MALLINFO_BODY \
|
|
/** Total number of non-mmapped bytes currently allocated from OS. */ \
|
|
size_t arena; \
|
|
/** Number of free chunks. */ \
|
|
size_t ordblks; \
|
|
/** (Unused.) */ \
|
|
size_t smblks; \
|
|
/** (Unused.) */ \
|
|
size_t hblks; \
|
|
/** Total number of bytes in mmapped regions. */ \
|
|
size_t hblkhd; \
|
|
/** Maximum total allocated space; greater than total if trimming has occurred. */ \
|
|
size_t usmblks; \
|
|
/** (Unused.) */ \
|
|
size_t fsmblks; \
|
|
/** Total allocated space (normal or mmapped.) */ \
|
|
size_t uordblks; \
|
|
/** Total free space. */ \
|
|
size_t fordblks; \
|
|
/** Upper bound on number of bytes releasable by a trim operation. */ \
|
|
size_t keepcost;
|
|
|
|
#ifndef STRUCT_MALLINFO_DECLARED
|
|
#define STRUCT_MALLINFO_DECLARED 1
|
|
struct mallinfo { __MALLINFO_BODY };
|
|
#endif
|
|
|
|
/**
|
|
* [mallinfo(3)](http://man7.org/linux/man-pages/man3/mallinfo.3.html) returns
|
|
* information about the current state of the heap. Note that mallinfo() is
|
|
* inherently unreliable and consider using malloc_info() instead.
|
|
*/
|
|
struct mallinfo mallinfo(void);
|
|
|
|
/**
|
|
* On Android the struct mallinfo and struct mallinfo2 are the same.
|
|
*/
|
|
struct mallinfo2 { __MALLINFO_BODY };
|
|
|
|
/**
|
|
* [mallinfo2(3)](http://man7.org/linux/man-pages/man3/mallinfo2.3.html) returns
|
|
* information about the current state of the heap. Note that mallinfo2() is
|
|
* inherently unreliable and consider using malloc_info() instead.
|
|
*/
|
|
struct mallinfo2 mallinfo2(void) __RENAME(mallinfo);
|
|
|
|
/**
|
|
* [malloc_info(3)](http://man7.org/linux/man-pages/man3/malloc_info.3.html)
|
|
* writes information about the current state of the heap to the given stream.
|
|
*
|
|
* The XML structure for malloc_info() is as follows:
|
|
* ```
|
|
* <malloc version="jemalloc-1">
|
|
* <heap nr="INT">
|
|
* <allocated-large>INT</allocated-large>
|
|
* <allocated-huge>INT</allocated-huge>
|
|
* <allocated-bins>INT</allocated-bins>
|
|
* <bins-total>INT</bins-total>
|
|
* <bin nr="INT">
|
|
* <allocated>INT</allocated>
|
|
* <nmalloc>INT</nmalloc>
|
|
* <ndalloc>INT</ndalloc>
|
|
* </bin>
|
|
* <!-- more bins -->
|
|
* </heap>
|
|
* <!-- more heaps -->
|
|
* </malloc>
|
|
* ```
|
|
*
|
|
* Available since API level 23.
|
|
*/
|
|
int malloc_info(int __must_be_zero, FILE* _Nonnull __fp) __INTRODUCED_IN(23);
|
|
|
|
/**
|
|
* mallopt() option to set the decay time. Valid values are 0 and 1.
|
|
*
|
|
* Available since API level 27.
|
|
*/
|
|
#define M_DECAY_TIME (-100)
|
|
/**
|
|
* mallopt() option to immediately purge any memory not in use. This
|
|
* will release the memory back to the kernel. The value is ignored.
|
|
*
|
|
* Available since API level 28.
|
|
*/
|
|
#define M_PURGE (-101)
|
|
/**
|
|
* mallopt() option to immediately purge all possible memory back to
|
|
* the kernel. This call can take longer than a normal purge since it
|
|
* examines everything. In some cases, it can take more than twice the
|
|
* time of a M_PURGE call. The value is ignored.
|
|
*
|
|
* Available since API level 34.
|
|
*/
|
|
#define M_PURGE_ALL (-104)
|
|
|
|
/**
|
|
* mallopt() option to tune the allocator's choice of memory tags to
|
|
* make it more likely that a certain class of memory errors will be
|
|
* detected. This is only relevant if MTE is enabled in this process
|
|
* and ignored otherwise. The value argument should be one of the
|
|
* M_MEMTAG_TUNING_* flags.
|
|
* NOTE: This is only available in scudo.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_MEMTAG_TUNING (-102)
|
|
|
|
/**
|
|
* When passed as a value of M_MEMTAG_TUNING mallopt() call, enables
|
|
* deterministic detection of linear buffer overflow and underflow
|
|
* bugs by assigning distinct tag values to adjacent allocations. This
|
|
* mode has a slightly reduced chance to detect use-after-free bugs
|
|
* because only half of the possible tag values are available for each
|
|
* memory location.
|
|
*
|
|
* Please keep in mind that MTE can not detect overflow within the
|
|
* same tag granule (16-byte aligned chunk), and can miss small
|
|
* overflows even in this mode. Such overflow can not be the cause of
|
|
* a memory corruption, because the memory within one granule is never
|
|
* used for multiple allocations.
|
|
*/
|
|
#define M_MEMTAG_TUNING_BUFFER_OVERFLOW 0
|
|
|
|
/**
|
|
* When passed as a value of M_MEMTAG_TUNING mallopt() call, enables
|
|
* independently randomized tags for uniform ~93% probability of
|
|
* detecting both spatial (buffer overflow) and temporal (use after
|
|
* free) bugs.
|
|
*/
|
|
#define M_MEMTAG_TUNING_UAF 1
|
|
|
|
/**
|
|
* mallopt() option for per-thread memory initialization tuning.
|
|
* The value argument should be one of:
|
|
* 1: Disable automatic heap initialization on this thread only.
|
|
* If memory tagging is enabled, disable as much as possible of the
|
|
* memory tagging initialization for this thread.
|
|
* 0: Normal behavior.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_THREAD_DISABLE_MEM_INIT (-103)
|
|
/**
|
|
* mallopt() option to set the maximum number of items in the secondary
|
|
* cache of the scudo allocator.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_CACHE_COUNT_MAX (-200)
|
|
/**
|
|
* mallopt() option to set the maximum size in bytes of a cacheable item in
|
|
* the secondary cache of the scudo allocator.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_CACHE_SIZE_MAX (-201)
|
|
/**
|
|
* mallopt() option to increase the maximum number of shared thread-specific
|
|
* data structures that can be created. This number cannot be decreased,
|
|
* only increased and only applies to the scudo allocator.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_TSDS_COUNT_MAX (-202)
|
|
|
|
/**
|
|
* mallopt() option to decide whether heap memory is zero-initialized on
|
|
* allocation across the whole process. May be called at any time, including
|
|
* when multiple threads are running. An argument of zero indicates memory
|
|
* should not be zero-initialized, any other value indicates to initialize heap
|
|
* memory to zero.
|
|
*
|
|
* Note that this memory mitigation is only implemented in scudo and therefore
|
|
* this will have no effect when using another allocator (such as jemalloc on
|
|
* Android Go devices).
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_BIONIC_ZERO_INIT (-203)
|
|
|
|
/**
|
|
* mallopt() option to change the heap tagging state. May be called at any
|
|
* time, including when multiple threads are running.
|
|
* The value must be one of the M_HEAP_TAGGING_LEVEL_ constants.
|
|
* NOTE: This is only available in scudo.
|
|
*
|
|
* Available since API level 31.
|
|
*/
|
|
#define M_BIONIC_SET_HEAP_TAGGING_LEVEL (-204)
|
|
|
|
/**
|
|
* Constants for use with the M_BIONIC_SET_HEAP_TAGGING_LEVEL mallopt() option.
|
|
*/
|
|
enum HeapTaggingLevel {
|
|
/**
|
|
* Disable heap tagging and memory tag checks (if supported).
|
|
* Heap tagging may not be re-enabled after being disabled.
|
|
*/
|
|
M_HEAP_TAGGING_LEVEL_NONE = 0,
|
|
#define M_HEAP_TAGGING_LEVEL_NONE M_HEAP_TAGGING_LEVEL_NONE
|
|
/**
|
|
* Address-only tagging. Heap pointers have a non-zero tag in the
|
|
* most significant ("top") byte which is checked in free(). Memory
|
|
* accesses ignore the tag using arm64's Top Byte Ignore (TBI) feature.
|
|
*/
|
|
M_HEAP_TAGGING_LEVEL_TBI = 1,
|
|
#define M_HEAP_TAGGING_LEVEL_TBI M_HEAP_TAGGING_LEVEL_TBI
|
|
/**
|
|
* Enable heap tagging and asynchronous memory tag checks (if supported).
|
|
* Disable stack trace collection.
|
|
*/
|
|
M_HEAP_TAGGING_LEVEL_ASYNC = 2,
|
|
#define M_HEAP_TAGGING_LEVEL_ASYNC M_HEAP_TAGGING_LEVEL_ASYNC
|
|
/**
|
|
* Enable heap tagging and synchronous memory tag checks (if supported).
|
|
* Enable stack trace collection.
|
|
*/
|
|
M_HEAP_TAGGING_LEVEL_SYNC = 3,
|
|
#define M_HEAP_TAGGING_LEVEL_SYNC M_HEAP_TAGGING_LEVEL_SYNC
|
|
};
|
|
|
|
/**
|
|
* mallopt() option to print human readable statistics about the memory
|
|
* allocator to the log. There is no format for this data, each allocator
|
|
* can use a different format, and the data that is printed can
|
|
* change at any time. This is expected to be used as a debugging aid.
|
|
*
|
|
* Available since API level 35.
|
|
*/
|
|
#define M_LOG_STATS (-205)
|
|
|
|
/**
|
|
* [mallopt(3)](http://man7.org/linux/man-pages/man3/mallopt.3.html) modifies
|
|
* heap behavior. Values of `__option` are the `M_` constants from this header.
|
|
*
|
|
* Returns 1 on success, 0 on error.
|
|
*
|
|
* Available since API level 26.
|
|
*/
|
|
int mallopt(int __option, int __value) __INTRODUCED_IN(26);
|
|
|
|
/**
|
|
* [__malloc_hook(3)](http://man7.org/linux/man-pages/man3/__malloc_hook.3.html)
|
|
* is called to implement malloc(). By default this points to the system's
|
|
* implementation.
|
|
*
|
|
* Available since API level 28.
|
|
*
|
|
* See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
|
|
*/
|
|
extern void* _Nonnull (*volatile _Nonnull __malloc_hook)(size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
|
|
|
|
/**
|
|
* [__realloc_hook(3)](http://man7.org/linux/man-pages/man3/__realloc_hook.3.html)
|
|
* is called to implement realloc(). By default this points to the system's
|
|
* implementation.
|
|
*
|
|
* Available since API level 28.
|
|
*
|
|
* See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
|
|
*/
|
|
extern void* _Nonnull (*volatile _Nonnull __realloc_hook)(void* _Nullable __ptr, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
|
|
|
|
/**
|
|
* [__free_hook(3)](http://man7.org/linux/man-pages/man3/__free_hook.3.html)
|
|
* is called to implement free(). By default this points to the system's
|
|
* implementation.
|
|
*
|
|
* Available since API level 28.
|
|
*
|
|
* See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
|
|
*/
|
|
extern void (*volatile _Nonnull __free_hook)(void* _Nullable __ptr, const void* _Nonnull __caller) __INTRODUCED_IN(28);
|
|
|
|
/**
|
|
* [__memalign_hook(3)](http://man7.org/linux/man-pages/man3/__memalign_hook.3.html)
|
|
* is called to implement memalign(). By default this points to the system's
|
|
* implementation.
|
|
*
|
|
* Available since API level 28.
|
|
*
|
|
* See also: [extra documentation](https://android.googlesource.com/platform/bionic/+/master/libc/malloc_hooks/README.md)
|
|
*/
|
|
extern void* _Nonnull (*volatile _Nonnull __memalign_hook)(size_t __alignment, size_t __byte_count, const void* _Nonnull __caller) __INTRODUCED_IN(28);
|
|
|
|
__END_DECLS
|