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 7Currently, malloc debug requires root to enable. When it is enabled, it works 8by adding a shim layer that replaces the normal allocation calls. The replaced 9calls are: 10 11<pre> 12malloc 13free 14calloc 15realloc 16posix_memalign 17memalign 18malloc_usable_size 19</pre> 20 21On 32 bit systems, these two deprecated functions are also replaced: 22 23<pre> 24pvalloc 25valloc 26</pre> 27 28Any errors detected by the library are reported in the log. 29 30Controlling Malloc Debug Behavior 31--------------------------------- 32Malloc debug is controlled by individual options. Each option can be enabled 33individually, or in a group of other options. Every single option can be 34combined with every other option. 35 36Option Descriptions 37------------------- 38### front\_guard[=SIZE\_BYTES] 39Enables a small buffer placed before the allocated data. This is an attempt 40to find memory corruption occuring to a region before the original allocation. 41On first allocation, this front guard is written with a specific pattern (0xaa). 42When the allocation is freed, the guard is checked to verify it has not been 43modified. If any part of the front guard is modified, an error will be reported 44in the log indicating what bytes changed. 45 46If the backtrace option is also enabled, then any error message will include 47the backtrace of the allocation site. 48 49If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 50The default is 32 bytes, the max bytes is 16384. SIZE\_BYTES will be 51padded so that it is a multiple of 8 bytes on 32 bit systems and 16 bytes 52on 64 bit systems to make sure that the allocation returned is aligned 53properly. 54 55This option adds a special header to all allocations that contains the guard 56and information about the original allocation. 57 58Example error: 59 60<pre> 6104-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED FRONT GUARD 6204-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-32] = 0x00 (expected 0xaa) 6304-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-15] = 0x02 (expected 0xaa) 64</pre> 65 66### rear\_guard[=SIZE\_BYTES] 67Enables a small buffer placed after the allocated data. This is an attempt 68to find memory corruption occuring to a region after the original allocation. 69On first allocation, this rear guard is written with a specific pattern (0xbb). 70When the allocation is freed, the guard is checked to verify it has not been 71modified. If any part of the rear guard is modified, an error will be reported 72in the log indicating what bytes changed. 73 74If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 75The default is 32 bytes, the max bytes is 16384. 76 77This option adds a special header to all allocations that contains 78information about the original allocation. 79 80Example error: 81 82<pre> 8304-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED REAR GUARD 8404-10 12:00:45.622 7412 7412 E malloc_debug: allocation[130] = 0xbf (expected 0xbb) 8504-10 12:00:45.622 7412 7412 E malloc_debug: allocation[131] = 0x00 (expected 0xbb) 86</pre> 87 88### guard[=SIZE\_BYTES] 89Enables both a front guard and a rear guard on all allocations. 90 91If SIZE\_BYTES is present, it indicates the number of bytes in both guards. 92The default is 32 bytes, the max bytes is 16384. 93 94### backtrace[=MAX\_FRAMES] 95Enable capturing the backtrace of each allocation site. 96This option will slow down allocations by an order of magnitude. If the 97system runs too slowly with this option enabled, decreasing the maximum number 98of frames captured will speed the allocations up. 99 100Note that any backtrace frames that occur within the malloc backtrace library 101itself are not recorded. 102 103If MAX\_FRAMES is present, it indicates the maximum number of frames to 104capture in a backtrace. The default is 16 frames, the maximumum value 105this can be set to is 256. 106 107This option adds a special header to all allocations that contains the 108backtrace and information about the original allocation. 109 110### backtrace\_enable\_on\_signal[=MAX\_FRAMES] 111Enable capturing the backtrace of each allocation site. If the 112backtrace capture is toggled when the process receives the signal 113SIGRTMAX - 19 (which is 45 on most Android devices). When this 114option is used alone, backtrace capture starts out disabled until the signal 115is received. If both this option and the backtrace option are set, then 116backtrace capture is enabled until the signal is received. 117 118If MAX\_FRAMES is present, it indicates the maximum number of frames to 119capture in a backtrace. The default is 16 frames, the maximumum value 120this can be set to is 256. 121 122This option adds a special header to all allocations that contains the 123backtrace and information about the original allocation. 124 125### fill\_on\_alloc[=MAX\_FILLED\_BYTES] 126Any allocation routine, other than calloc, will result in the allocation being 127filled with the value 0xeb. When doing a realloc to a larger size, the bytes 128above the original usable size will be set to 0xeb. 129 130If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 131of bytes in the allocation. The default is to fill the entire allocation. 132 133### fill\_on\_free[=MAX\_FILLED\_BYTES] 134When an allocation is freed, fill it with 0xef. 135 136If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 137of bytes in the allocation. The default is to fill the entire allocation. 138 139### fill[=MAX\_FILLED\_BYTES] 140This enables both the fill\_on\_alloc option and the fill\_on\_free option. 141 142If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 143of bytes in the allocation. The default is to fill the entire allocation. 144 145### expand\_alloc[=EXPAND\_BYTES] 146Add an extra amount to allocate for every allocation. 147 148If XX is present, it is the number of bytes to expand the allocation by. 149The default is 16 bytes, the max bytes is 16384. 150 151### free\_track[=ALLOCATION\_COUNT] 152When a pointer is freed, do not free the memory right away, but add it to 153a list of freed allocations. In addition to being added to the list, the 154entire allocation is filled with the value 0xef, and the backtrace at 155the time of the free is recorded. The backtrace recording is completely 156separate from the backtrace option, and happens automatically if this 157option is enabled. By default, a maximum of 16 frames will be recorded, 158but this value can be changed using the free\_track\_backtrace\_num\_frames 159option. It can also be completely disabled by setting the option to zero. 160See the full description of this option below. 161 162When the list is full, an allocation is removed from the list and is 163checked to make sure that none of the contents have been modified since 164being placed on the list. When the program terminates, all of the allocations 165left on the list are verified. 166 167If ALLOCATION\_COUNT is present, it indicates the total number of allocations 168in the list. The default is to record 100 freed allocations, the max 169allocations to record is 16384. 170 171This option adds a special header to all allocations that contains 172information about the original allocation. 173 174Example error: 175 176<pre> 17704-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE 17804-15 12:00:31.305 7412 7412 E malloc_debug: allocation[20] = 0xaf (expected 0xef) 17904-15 12:00:31.305 7412 7412 E malloc_debug: allocation[99] = 0x12 (expected 0xef) 18004-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of free: 18104-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 18204-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 18304-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 18404-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 185</pre> 186 187In addition, there is another type of error message that can occur if 188an allocation has a special header applied, and the header is corrupted 189before the verification occurs. This is the error message that will be found 190in the log: 191 192<pre> 193+++ ALLOCATION 0x12345678 HAS CORRUPTED HEADER TAG 0x1cc7dc00 AFTER FREE 194</pre> 195 196### free\_track\_backtrace\_num\_frames[=MAX\_FRAMES] 197This option only has meaning if free\_track is set. It indicates how many 198backtrace frames to capture when an allocation is freed. 199 200If MAX\_FRAMES is present, it indicates the number of frames to capture. 201If the value is set to zero, then no backtrace will be captured when the 202allocation is freed. The default is to record 16 frames, the max number of 203frames to to record is 256. 204 205### leak\_track 206Track all live allocations. When the program terminates, all of the live 207allocations will be dumped to the log. If the backtrace option was enabled, 208then the log will include the backtrace of the leaked allocations. This 209option is not useful when enabled globally because a lot of programs do not 210free everything before the program terminates. 211 212This option adds a special header to all allocations that contains 213information about the original allocation. 214 215Example leak error found in the log: 216 217<pre> 21804-15 12:35:33.304 7412 7412 E malloc_debug: +++ APP leaked block of size 100 at 0x2be3b0b0 (leak 1 of 2) 21904-15 12:35:33.304 7412 7412 E malloc_debug: Backtrace at time of allocation: 22004-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 22104-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 22204-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 22304-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 22404-15 12:35:33.305 7412 7412 E malloc_debug: +++ APP leaked block of size 24 at 0x7be32380 (leak 2 of 2) 22504-15 12:35:33.305 7412 7412 E malloc_debug: Backtrace at time of allocation: 22604-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 22704-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 22804-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 22904-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 230</pre> 231 232Additional Errors 233----------------- 234There are a few other error messages that might appear in the log. 235 236### Use After Free 237<pre> 23804-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (free) 23904-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace of original free: 24004-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 24104-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 24204-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 24304-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 24404-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 24504-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 24604-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 24704-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 24804-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 249</pre> 250 251This indicates that code is attempting to free an already freed pointer. The 252name in parenthesis indicates that the application called the function 253<i>free</i> with the bad pointer. 254 255For example, this message: 256 257<pre> 25804-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (realloc) 259</pre> 260 261Would indicate that the application called the <i>realloc</i> function 262with an already freed pointer. 263 264### Invalid Tag 265<pre> 26604-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS INVALID TAG 1ee7d000 (malloc_usable_size) 26704-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 26804-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 26904-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 27004-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 27104-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 272</pre> 273 274This indicates that a function (malloc\_usable\_size) was called with 275a pointer that is either not allocated memory, or that the memory of 276the pointer has been corrupted. 277 278As with the other error message, the function in parenthesis is the 279function that was called with the bad pointer. 280 281Examples 282======== 283Enable backtrace tracking of all allocation for all processes: 284 285<pre> 286 adb shell stop 287 adb shell setprop libc.debug.malloc.options backtrace 288 adb shell start 289</pre> 290 291Enable backtrace tracking for a specific process (ls): 292 293<pre> 294 adb shell setprop libc.debug.malloc.options backtrace 295 adb shell setprop libc.debug.malloc.program ls 296 adb shell ls 297</pre> 298 299Enable backtrace tracking for the zygote and zygote based processes: 300 301<pre> 302 adb shell stop 303 adb shell setprop libc.debug.malloc.program app_process 304 adb shell setprop libc.debug.malloc.options backtrace 305 adb shell start 306</pre> 307 308Enable multiple options (backtrace and guards): 309 310<pre> 311 adb shell stop 312 adb shell setprop libc.debug.malloc.options "\"backtrace guards\"" 313 adb shell start 314</pre> 315 316Enable malloc debug when multiple processes have the same name. This method 317can be used to enable malloc debug for only a very specific process if 318multiple processes have the same name. 319 320Note: The double quotes in the adb shell command are necessary. Otherwise, 321the setprop command will fail since the backtrace guards options will look 322like two arguments instead of one. 323 324<pre> 325 adb shell 326 # setprop libc.debug.malloc.env_enabled 327 # setprop libc.debug.malloc.options backtrace 328 # export LIBC_DEBUG_MALLOC_ENABLE 1 329 # ls 330</pre> 331