| Malloc Debug | |
| ============ | |
| Malloc debug is a method of debugging native memory problems. It can help | |
| detect memory corruption, memory leaks, and use after free issues. | |
| This documentation describes how to enable this feature on Android N or later | |
| versions of the Android OS. | |
| The documentation for malloc debug on older versions of Android is | |
| [here](README_marshmallow_and_earlier.md). | |
| In order to enable malloc debug, you must be able to set special system | |
| properties using the setprop command from the shell. This requires the | |
| ability to run as root on the device. | |
| When malloc debug is enabled, it works by adding a shim layer that replaces | |
| the normal allocation calls. The replaced calls are: | |
| * `malloc` | |
| * `free` | |
| * `calloc` | |
| * `realloc` | |
| * `posix_memalign` | |
| * `memalign` | |
| * `malloc_usable_size` | |
| On 32 bit systems, these two deprecated functions are also replaced: | |
| * `pvalloc` | |
| * `valloc` | |
| Any errors detected by the library are reported in the log. | |
| Controlling Malloc Debug Behavior | |
| --------------------------------- | |
| Malloc debug is controlled by individual options. Each option can be enabled | |
| individually, or in a group of other options. Every single option can be | |
| combined with every other option. | |
| Option Descriptions | |
| ------------------- | |
| ### front\_guard[=SIZE\_BYTES] | |
| Enables a small buffer placed before the allocated data. This is an attempt | |
| to find memory corruption occuring to a region before the original allocation. | |
| On first allocation, this front guard is written with a specific pattern (0xaa). | |
| When the allocation is freed, the guard is checked to verify it has not been | |
| modified. If any part of the front guard is modified, an error will be reported | |
| in the log indicating what bytes changed. | |
| If the backtrace option is also enabled, then any error message will include | |
| the backtrace of the allocation site. | |
| If SIZE\_BYTES is present, it indicates the number of bytes in the guard. | |
| The default is 32 bytes, the max bytes is 16384. SIZE\_BYTES will be | |
| padded so that it is a multiple of 8 bytes on 32 bit systems and 16 bytes | |
| on 64 bit systems to make sure that the allocation returned is aligned | |
| properly. | |
| This option adds a special header to all allocations that contains the guard | |
| and information about the original allocation. | |
| Example error: | |
| 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED FRONT GUARD | |
| 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-32] = 0x00 (expected 0xaa) | |
| 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-15] = 0x02 (expected 0xaa) | |
| ### rear\_guard[=SIZE\_BYTES] | |
| Enables a small buffer placed after the allocated data. This is an attempt | |
| to find memory corruption occuring to a region after the original allocation. | |
| On first allocation, this rear guard is written with a specific pattern (0xbb). | |
| When the allocation is freed, the guard is checked to verify it has not been | |
| modified. If any part of the rear guard is modified, an error will be reported | |
| in the log indicating what bytes changed. | |
| If SIZE\_BYTES is present, it indicates the number of bytes in the guard. | |
| The default is 32 bytes, the max bytes is 16384. | |
| This option adds a special header to all allocations that contains | |
| information about the original allocation. | |
| Example error: | |
| 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED REAR GUARD | |
| 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[130] = 0xbf (expected 0xbb) | |
| 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[131] = 0x00 (expected 0xbb) | |
| ### guard[=SIZE\_BYTES] | |
| Enables both a front guard and a rear guard on all allocations. | |
| If SIZE\_BYTES is present, it indicates the number of bytes in both guards. | |
| The default is 32 bytes, the max bytes is 16384. | |
| ### backtrace[=MAX\_FRAMES] | |
| Enable capturing the backtrace of each allocation site. | |
| This option will slow down allocations by an order of magnitude. If the | |
| system runs too slowly with this option enabled, decreasing the maximum number | |
| of frames captured will speed the allocations up. | |
| Note that any backtrace frames that occur within the malloc backtrace library | |
| itself are not recorded. | |
| If MAX\_FRAMES is present, it indicates the maximum number of frames to | |
| capture in a backtrace. The default is 16 frames, the maximumum value | |
| this can be set to is 256. | |
| This option adds a special header to all allocations that contains the | |
| backtrace and information about the original allocation. | |
| ### backtrace\_enable\_on\_signal[=MAX\_FRAMES] | |
| Enable capturing the backtrace of each allocation site. If the | |
| backtrace capture is toggled when the process receives the signal | |
| SIGRTMAX - 19 (which is 45 on most Android devices). When this | |
| option is used alone, backtrace capture starts out disabled until the signal | |
| is received. If both this option and the backtrace option are set, then | |
| backtrace capture is enabled until the signal is received. | |
| If MAX\_FRAMES is present, it indicates the maximum number of frames to | |
| capture in a backtrace. The default is 16 frames, the maximumum value | |
| this can be set to is 256. | |
| This option adds a special header to all allocations that contains the | |
| backtrace and information about the original allocation. | |
| ### fill\_on\_alloc[=MAX\_FILLED\_BYTES] | |
| Any allocation routine, other than calloc, will result in the allocation being | |
| filled with the value 0xeb. When doing a realloc to a larger size, the bytes | |
| above the original usable size will be set to 0xeb. | |
| If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number | |
| of bytes in the allocation. The default is to fill the entire allocation. | |
| ### fill\_on\_free[=MAX\_FILLED\_BYTES] | |
| When an allocation is freed, fill it with 0xef. | |
| If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number | |
| of bytes in the allocation. The default is to fill the entire allocation. | |
| ### fill[=MAX\_FILLED\_BYTES] | |
| This enables both the fill\_on\_alloc option and the fill\_on\_free option. | |
| If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number | |
| of bytes in the allocation. The default is to fill the entire allocation. | |
| ### expand\_alloc[=EXPAND\_BYTES] | |
| Add an extra amount to allocate for every allocation. | |
| If XX is present, it is the number of bytes to expand the allocation by. | |
| The default is 16 bytes, the max bytes is 16384. | |
| ### free\_track[=ALLOCATION\_COUNT] | |
| When a pointer is freed, do not free the memory right away, but add it to | |
| a list of freed allocations. In addition to being added to the list, the | |
| entire allocation is filled with the value 0xef, and the backtrace at | |
| the time of the free is recorded. The backtrace recording is completely | |
| separate from the backtrace option, and happens automatically if this | |
| option is enabled. By default, a maximum of 16 frames will be recorded, | |
| but this value can be changed using the free\_track\_backtrace\_num\_frames | |
| option. It can also be completely disabled by setting the option to zero. | |
| See the full description of this option below. | |
| When the list is full, an allocation is removed from the list and is | |
| checked to make sure that none of the contents have been modified since | |
| being placed on the list. When the program terminates, all of the allocations | |
| left on the list are verified. | |
| If ALLOCATION\_COUNT is present, it indicates the total number of allocations | |
| in the list. The default is to record 100 freed allocations, the max | |
| allocations to record is 16384. | |
| This option adds a special header to all allocations that contains | |
| information about the original allocation. | |
| Example error: | |
| 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[20] = 0xaf (expected 0xef) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[99] = 0x12 (expected 0xef) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of free: | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| In addition, there is another type of error message that can occur if | |
| an allocation has a special header applied, and the header is corrupted | |
| before the verification occurs. This is the error message that will be found | |
| in the log: | |
| 04-15 12:00:31.604 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS CORRUPTED HEADER TAG 0x1cc7dc00 AFTER FREE | |
| ### free\_track\_backtrace\_num\_frames[=MAX\_FRAMES] | |
| This option only has meaning if free\_track is set. It indicates how many | |
| backtrace frames to capture when an allocation is freed. | |
| If MAX\_FRAMES is present, it indicates the number of frames to capture. | |
| If the value is set to zero, then no backtrace will be captured when the | |
| allocation is freed. The default is to record 16 frames, the max number of | |
| frames to to record is 256. | |
| ### leak\_track | |
| Track all live allocations. When the program terminates, all of the live | |
| allocations will be dumped to the log. If the backtrace option was enabled, | |
| then the log will include the backtrace of the leaked allocations. This | |
| option is not useful when enabled globally because a lot of programs do not | |
| free everything before the program terminates. | |
| This option adds a special header to all allocations that contains | |
| information about the original allocation. | |
| Example leak error found in the log: | |
| 04-15 12:35:33.304 7412 7412 E malloc_debug: +++ APP leaked block of size 100 at 0x2be3b0b0 (leak 1 of 2) | |
| 04-15 12:35:33.304 7412 7412 E malloc_debug: Backtrace at time of allocation: | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: +++ APP leaked block of size 24 at 0x7be32380 (leak 2 of 2) | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: Backtrace at time of allocation: | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| ### record\_allocs[=TOTAL\_ENTRIES] | |
| Keep track of every allocation/free made on every thread and dump them | |
| to a file when the signal SIGRTMAX - 18 (which is 46 on most Android devices) | |
| is received. | |
| If TOTAL\_ENTRIES is set, then it indicates the total number of | |
| allocation/free records that can be retained. If the number of records | |
| reaches the TOTAL\_ENTRIES value, then any further allocations/frees are | |
| not recorded. The default value is 8,000,000 and the maximum value this | |
| can be set to is 50,000,000. | |
| Once the signal is received, and the current records are written to the | |
| file, all current records are deleted. Any allocations/frees occuring while | |
| the data is being dumped to the file are ignored. | |
| **NOTE**: This option is not available until the O release of Android. | |
| The allocation data is written in a human readable format. Every line begins | |
| with the THREAD\_ID returned by gettid(), which is the thread that is making | |
| the allocation/free. If a new thread is created, no special line is added | |
| to the file. However, when a thread completes, a special entry is added to | |
| the file indicating this. | |
| The thread complete line is: | |
| **THREAD\_ID**: thread\_done 0x0 | |
| Example: | |
| 187: thread_done 0x0 | |
| Below is how each type of allocation/free call ends up in the file dump. | |
| pointer = malloc(size) | |
| **THREAD\_ID**: malloc pointer size | |
| Example: | |
| 186: malloc 0xb6038060 20 | |
| free(pointer) | |
| **THREAD\_ID**: free pointer | |
| Example: | |
| 186: free 0xb6038060 | |
| pointer = calloc(nmemb, size) | |
| **THREAD\_ID**: calloc pointer nmemb size | |
| Example: | |
| 186: calloc 0xb609f080 32 4 | |
| new\_pointer = realloc(old\_pointer, size) | |
| **THREAD\_ID**: realloc new\_pointer old\_pointer size | |
| Example: | |
| 186: realloc 0xb609f080 0xb603e9a0 12 | |
| pointer = memalign(alignment, size) | |
| **THREAD\_ID**: memalign pointer alignment size | |
| posix\_memalign(&pointer, alignment, size) | |
| **THREAD\_ID**: memalign pointer alignment size | |
| Example: | |
| 186: memalign 0x85423660 16 104 | |
| pointer = valloc(size) | |
| **THREAD\_ID**: memalign pointer 4096 size | |
| Example: | |
| 186: memalign 0x85423660 4096 112 | |
| pointer = pvalloc(size) | |
| **THREAD\_ID**: memalign pointer 4096 <b>SIZE\_ROUNDED\_UP\_TO\_4096</b> | |
| Example: | |
| 186: memalign 0x85423660 4096 8192 | |
| ### record\_allocs\_file[=FILE\_NAME] | |
| This option only has meaning if record\_allocs is set. It indicates the | |
| file where the recorded allocations will be found. | |
| If FILE\_NAME is set, then it indicates where the record allocation data | |
| will be placed. | |
| **NOTE**: This option is not available until the O release of Android. | |
| Additional Errors | |
| ----------------- | |
| There are a few other error messages that might appear in the log. | |
| ### Use After Free | |
| 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (free) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace of original free: | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| This indicates that code is attempting to free an already freed pointer. The | |
| name in parenthesis indicates that the application called the function | |
| *free* with the bad pointer. | |
| For example, this message: | |
| 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (realloc) | |
| Would indicate that the application called the *realloc* function | |
| with an already freed pointer. | |
| ### Invalid Tag | |
| 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS INVALID TAG 1ee7d000 (malloc_usable_size) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so | |
| 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so | |
| This indicates that a function (malloc\_usable\_size) was called with | |
| a pointer that is either not allocated memory, or that the memory of | |
| the pointer has been corrupted. | |
| As with the other error message, the function in parenthesis is the | |
| function that was called with the bad pointer. | |
| Examples | |
| ======== | |
| Enable backtrace tracking of all allocation for all processes: | |
| adb shell stop | |
| adb shell setprop libc.debug.malloc.options backtrace | |
| adb shell start | |
| Enable backtrace tracking for a specific process (ls): | |
| adb shell setprop libc.debug.malloc.options backtrace | |
| adb shell setprop libc.debug.malloc.program ls | |
| adb shell ls | |
| Enable backtrace tracking for the zygote and zygote based processes: | |
| adb shell stop | |
| adb shell setprop libc.debug.malloc.program app_process | |
| adb shell setprop libc.debug.malloc.options backtrace | |
| adb shell start | |
| Enable multiple options (backtrace and guards): | |
| adb shell stop | |
| adb shell setprop libc.debug.malloc.options "\"backtrace guards\"" | |
| adb shell start | |
| Enable malloc debug when multiple processes have the same name. This method | |
| can be used to enable malloc debug for only a very specific process if | |
| multiple processes have the same name. | |
| Note: The double quotes in the adb shell command are necessary. Otherwise, | |
| the setprop command will fail since the backtrace guards options will look | |
| like two arguments instead of one. | |
| adb shell | |
| # setprop libc.debug.malloc.env_enabled | |
| # setprop libc.debug.malloc.options backtrace | |
| # export LIBC_DEBUG_MALLOC_ENABLE 1 | |
| # ls | |
| Enable malloc debug and dump the native allocation with backtraces to | |
| a file. This only works for zygote based java processes. | |
| adb shell stop | |
| adb shell setprop libc.debug.malloc.options backtrace | |
| adb shell start | |
| adb shell am dumpheap -n <PID_TO_DUMP> /data/local/tmp/heap.txt | |
| It is possible to use the backtrace\_enable\_on\_signal option as well, | |
| but it must be enabled through the signal before the file will contain | |
| any data. |