1Malloc Debug 2============ 3 4Malloc debug is a method of debugging native memory problems. It can help 5detect memory corruption, memory leaks, and use after free issues. 6 7This documentation describes how to enable this feature on API level 823 or older. Note: malloc debug was full of bugs and was not fully 9functional until API level 19, so using it on a version older than that 10is not guaranteed to work at all. 11 12The documentation for malloc debug on newer versions of Android is 13[here](README.md). 14 15On these old versions of the OS, you must be able to set system properties 16using the setprop command from the shell. This requires the ability to 17run as root on the device. 18 19When malloc debug is enabled, it works by adding a shim layer that replaces 20the normal allocation calls. The replaced calls are: 21 22* `malloc` 23* `free` 24* `calloc` 25* `realloc` 26* `posix_memalign` 27* `memalign` 28* `malloc_usable_size` 29 30On 32 bit systems, these two deprecated functions are also replaced: 31 32* `pvalloc` 33* `valloc` 34 35Any errors detected by the library are reported in the log. 36 37Controlling Malloc Debug Behavior 38--------------------------------- 39Malloc debug is controlled by a system property that takes a numeric value 40named libc.debug.malloc. It has only a few distinct modes that enables a 41set of different malloc debug checks at once. 42 43Value 1 44-------- 45When enabled, this value creates a special header to all allocations 46that contains information about the allocation. 47 48### Backtrace at Allocation Creation 49Enable capturing the backtrace of each allocation site. Only the 50first 16 frames of the backtrace will be captured. 51This option will slow down allocations by an order of magnitude, and 52might cause timeouts when trying to start a device. 53 54### Track Live Allocations 55All of the currently live allocations will be tracked and can be retrieved 56by a call to get\_malloc\_leak\_info (see README\_api.md for details). 57 58Note: If multiple allocations have the same exact backtrace, then only one 59entry is returned in the list. 60 61Value 5 62------- 63When enabled, this value does not create a special header. It only modifies 64the content of allocations. 65 66Whenever an allocation is created, initialize the data with a known 67pattern (0xeb). This does not happen for the calloc calls. 68Whenever an allocation is freed, write a known pattern over the data (0xef). 69 70Value 10 71-------- 72When enabled, this value creates a special header to all allocations 73that contains information about the allocation. 74 75This value enables everything enabled with value 1 plus these other options. 76 77### Allocation Guards 78A 32 byte buffer is placed before the returned allocation (known as 79a front guard). This buffer is filled with the pattern (0xaa). In addition, 80a 32 byte buffer is placed after the data for the returned allocation (known 81as a rear guard). This buffer is filled with the pattern (0xbb). 82 83When the allocation is freed, both of these guards are verified to contain 84the expected patterns. If not, then an error message is printed to the log. 85 86### Free Memory Tracking 87When a pointer is freed, do not free the memory right away, but add it to 88a list of freed allocations. In addition to being added to the list, the 89entire allocation is filled with the value 0xef, and the backtrace at 90the time of the free is recorded. As with the backtrace on allocation, 91only up to 16 frames will be recorded. 92 93When the list of freed allocations reaches 100, the oldest allocation 94on the list is removed and verified that it still contains the pattern 0xef. 95If the entire allocation is not filled with this value, an error is printed 96to the log. 97 98### Log Leaks 99When the program completes, all of the allocations that are still live 100are printed to the log as leaks. This isn't very useful since it tends 101to display a lot of false positive because many programs do not free 102everything before terminating. 103 104Option 20 105--------- 106Do not use this option value, it only works on the emulator. It has not 107been verified, so it may or may not work. 108 109Enable on Certain Processes 110--------------------------- 111Using the special system property, libc.debug.malloc.program, will 112cause malloc debug to only be used on processes with that name. For example, 113if the property is set to ls, then only the program named ls will have malloc 114debug enabled. 115 116Examples 117======== 118Enable malloc debug for all allocations for all processes: 119 120 adb shell stop 121 adb shell setprop libc.debug.malloc 1 122 adb shell start 123 124Enable malloc debug for a particular process: 125 126 adb shell setprop libc.debug.malloc.program ls 127 adb shell setprop libc.debug.malloc 10 128 adb shell ls /data/local/tmp 129