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 Android N or later 8versions of the Android OS. 9 10The documentation for malloc debug on older versions of Android is 11[here](README_marshmallow_and_earlier.md). 12 13In order to enable malloc debug, you must be able to set special system 14properties using the setprop command from the shell. This requires the 15ability to run as root on the device. 16 17When malloc debug is enabled, it works by adding a shim layer that replaces 18the normal allocation calls. The replaced calls are: 19 20* `malloc` 21* `free` 22* `calloc` 23* `realloc` 24* `posix_memalign` 25* `memalign` 26* `malloc_usable_size` 27 28On 32 bit systems, these two deprecated functions are also replaced: 29 30* `pvalloc` 31* `valloc` 32 33Any errors detected by the library are reported in the log. 34 35Controlling Malloc Debug Behavior 36--------------------------------- 37Malloc debug is controlled by individual options. Each option can be enabled 38individually, or in a group of other options. Every single option can be 39combined with every other option. 40 41Option Descriptions 42------------------- 43### front\_guard[=SIZE\_BYTES] 44Enables a small buffer placed before the allocated data. This is an attempt 45to find memory corruption occuring to a region before the original allocation. 46On first allocation, this front guard is written with a specific pattern (0xaa). 47When the allocation is freed, the guard is checked to verify it has not been 48modified. If any part of the front guard is modified, an error will be reported 49in the log indicating what bytes changed. 50 51If the backtrace option is also enabled, then any error message will include 52the backtrace of the allocation site. 53 54If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 55The default is 32 bytes, the max bytes is 16384. SIZE\_BYTES will be 56padded so that it is a multiple of 8 bytes on 32 bit systems and 16 bytes 57on 64 bit systems to make sure that the allocation returned is aligned 58properly. 59 60This option adds a special header to all allocations that contains the guard 61and information about the original allocation. 62 63Example error: 64 65 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED FRONT GUARD 66 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-32] = 0x00 (expected 0xaa) 67 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-15] = 0x02 (expected 0xaa) 68 69### rear\_guard[=SIZE\_BYTES] 70Enables a small buffer placed after the allocated data. This is an attempt 71to find memory corruption occuring to a region after the original allocation. 72On first allocation, this rear guard is written with a specific pattern (0xbb). 73When the allocation is freed, the guard is checked to verify it has not been 74modified. If any part of the rear guard is modified, an error will be reported 75in the log indicating what bytes changed. 76 77If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 78The default is 32 bytes, the max bytes is 16384. 79 80This option adds a special header to all allocations that contains 81information about the original allocation. 82 83Example error: 84 85 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED REAR GUARD 86 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[130] = 0xbf (expected 0xbb) 87 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[131] = 0x00 (expected 0xbb) 88 89### guard[=SIZE\_BYTES] 90Enables both a front guard and a rear guard on all allocations. 91 92If SIZE\_BYTES is present, it indicates the number of bytes in both guards. 93The default is 32 bytes, the max bytes is 16384. 94 95### backtrace[=MAX\_FRAMES] 96Enable capturing the backtrace of each allocation site. 97This option will slow down allocations by an order of magnitude. If the 98system runs too slowly with this option enabled, decreasing the maximum number 99of frames captured will speed the allocations up. 100 101Note that any backtrace frames that occur within the malloc backtrace library 102itself are not recorded. 103 104If MAX\_FRAMES is present, it indicates the maximum number of frames to 105capture in a backtrace. The default is 16 frames, the maximumum value 106this can be set to is 256. 107 108This option adds a special header to all allocations that contains the 109backtrace and information about the original allocation. 110 111### backtrace\_enable\_on\_signal[=MAX\_FRAMES] 112Enable capturing the backtrace of each allocation site. If the 113backtrace capture is toggled when the process receives the signal 114SIGRTMAX - 19 (which is 45 on most Android devices). When this 115option is used alone, backtrace capture starts out disabled until the signal 116is received. If both this option and the backtrace option are set, then 117backtrace capture is enabled until the signal is received. 118 119If MAX\_FRAMES is present, it indicates the maximum number of frames to 120capture in a backtrace. The default is 16 frames, the maximumum value 121this can be set to is 256. 122 123This option adds a special header to all allocations that contains the 124backtrace and information about the original allocation. 125 126### fill\_on\_alloc[=MAX\_FILLED\_BYTES] 127Any allocation routine, other than calloc, will result in the allocation being 128filled with the value 0xeb. When doing a realloc to a larger size, the bytes 129above the original usable size will be set to 0xeb. 130 131If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 132of bytes in the allocation. The default is to fill the entire allocation. 133 134### fill\_on\_free[=MAX\_FILLED\_BYTES] 135When an allocation is freed, fill it with 0xef. 136 137If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 138of bytes in the allocation. The default is to fill the entire allocation. 139 140### fill[=MAX\_FILLED\_BYTES] 141This enables both the fill\_on\_alloc option and the fill\_on\_free option. 142 143If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 144of bytes in the allocation. The default is to fill the entire allocation. 145 146### expand\_alloc[=EXPAND\_BYTES] 147Add an extra amount to allocate for every allocation. 148 149If XX is present, it is the number of bytes to expand the allocation by. 150The default is 16 bytes, the max bytes is 16384. 151 152### free\_track[=ALLOCATION\_COUNT] 153When a pointer is freed, do not free the memory right away, but add it to 154a list of freed allocations. In addition to being added to the list, the 155entire allocation is filled with the value 0xef, and the backtrace at 156the time of the free is recorded. The backtrace recording is completely 157separate from the backtrace option, and happens automatically if this 158option is enabled. By default, a maximum of 16 frames will be recorded, 159but this value can be changed using the free\_track\_backtrace\_num\_frames 160option. It can also be completely disabled by setting the option to zero. 161See the full description of this option below. 162 163When the list is full, an allocation is removed from the list and is 164checked to make sure that none of the contents have been modified since 165being placed on the list. When the program terminates, all of the allocations 166left on the list are verified. 167 168If ALLOCATION\_COUNT is present, it indicates the total number of allocations 169in the list. The default is to record 100 freed allocations, the max 170allocations to record is 16384. 171 172This option adds a special header to all allocations that contains 173information about the original allocation. 174 175Example error: 176 177 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE 178 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[20] = 0xaf (expected 0xef) 179 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[99] = 0x12 (expected 0xef) 180 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of free: 181 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 182 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 183 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 184 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 185 186In addition, there is another type of error message that can occur if 187an allocation has a special header applied, and the header is corrupted 188before the verification occurs. This is the error message that will be found 189in the log: 190 191 04-15 12:00:31.604 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS CORRUPTED HEADER TAG 0x1cc7dc00 AFTER FREE 192 193### free\_track\_backtrace\_num\_frames[=MAX\_FRAMES] 194This option only has meaning if free\_track is set. It indicates how many 195backtrace frames to capture when an allocation is freed. 196 197If MAX\_FRAMES is present, it indicates the number of frames to capture. 198If the value is set to zero, then no backtrace will be captured when the 199allocation is freed. The default is to record 16 frames, the max number of 200frames to to record is 256. 201 202### leak\_track 203Track all live allocations. When the program terminates, all of the live 204allocations will be dumped to the log. If the backtrace option was enabled, 205then the log will include the backtrace of the leaked allocations. This 206option is not useful when enabled globally because a lot of programs do not 207free everything before the program terminates. 208 209This option adds a special header to all allocations that contains 210information about the original allocation. 211 212Example leak error found in the log: 213 214 04-15 12:35:33.304 7412 7412 E malloc_debug: +++ APP leaked block of size 100 at 0x2be3b0b0 (leak 1 of 2) 215 04-15 12:35:33.304 7412 7412 E malloc_debug: Backtrace at time of allocation: 216 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 217 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 218 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 219 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 220 04-15 12:35:33.305 7412 7412 E malloc_debug: +++ APP leaked block of size 24 at 0x7be32380 (leak 2 of 2) 221 04-15 12:35:33.305 7412 7412 E malloc_debug: Backtrace at time of allocation: 222 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 223 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 224 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 225 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 226 227### record\_allocs[=TOTAL\_ENTRIES] 228Keep track of every allocation/free made on every thread and dump them 229to a file when the signal SIGRTMAX - 18 (which is 46 on most Android devices) 230is received. 231 232If TOTAL\_ENTRIES is set, then it indicates the total number of 233allocation/free records that can be retained. If the number of records 234reaches the TOTAL\_ENTRIES value, then any further allocations/frees are 235not recorded. The default value is 8,000,000 and the maximum value this 236can be set to is 50,000,000. 237 238Once the signal is received, and the current records are written to the 239file, all current records are deleted. Any allocations/frees occuring while 240the data is being dumped to the file are ignored. 241 242**NOTE**: This option is not available until the O release of Android. 243 244The allocation data is written in a human readable format. Every line begins 245with the THREAD\_ID returned by gettid(), which is the thread that is making 246the allocation/free. If a new thread is created, no special line is added 247to the file. However, when a thread completes, a special entry is added to 248the file indicating this. 249 250The thread complete line is: 251 252**THREAD\_ID**: thread\_done 0x0 253 254Example: 255 256 187: thread_done 0x0 257 258Below is how each type of allocation/free call ends up in the file dump. 259 260pointer = malloc(size) 261 262**THREAD\_ID**: malloc pointer size 263 264Example: 265 266 186: malloc 0xb6038060 20 267 268free(pointer) 269 270**THREAD\_ID**: free pointer 271 272Example: 273 274 186: free 0xb6038060 275 276pointer = calloc(nmemb, size) 277 278**THREAD\_ID**: calloc pointer nmemb size 279 280Example: 281 282 186: calloc 0xb609f080 32 4 283 284new\_pointer = realloc(old\_pointer, size) 285 286**THREAD\_ID**: realloc new\_pointer old\_pointer size 287 288Example: 289 290 186: realloc 0xb609f080 0xb603e9a0 12 291 292pointer = memalign(alignment, size) 293 294**THREAD\_ID**: memalign pointer alignment size 295 296posix\_memalign(&pointer, alignment, size) 297 298**THREAD\_ID**: memalign pointer alignment size 299 300Example: 301 302 186: memalign 0x85423660 16 104 303 304pointer = valloc(size) 305 306**THREAD\_ID**: memalign pointer 4096 size 307 308Example: 309 310 186: memalign 0x85423660 4096 112 311 312pointer = pvalloc(size) 313 314**THREAD\_ID**: memalign pointer 4096 <b>SIZE\_ROUNDED\_UP\_TO\_4096</b> 315 316Example: 317 318 186: memalign 0x85423660 4096 8192 319 320### record\_allocs\_file[=FILE\_NAME] 321This option only has meaning if record\_allocs is set. It indicates the 322file where the recorded allocations will be found. 323 324If FILE\_NAME is set, then it indicates where the record allocation data 325will be placed. 326 327**NOTE**: This option is not available until the O release of Android. 328 329Additional Errors 330----------------- 331There are a few other error messages that might appear in the log. 332 333### Use After Free 334 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (free) 335 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace of original free: 336 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 337 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 338 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 339 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 340 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 341 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 342 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 343 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 344 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 345 346This indicates that code is attempting to free an already freed pointer. The 347name in parenthesis indicates that the application called the function 348*free* with the bad pointer. 349 350For example, this message: 351 352 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (realloc) 353 354Would indicate that the application called the *realloc* function 355with an already freed pointer. 356 357### Invalid Tag 358 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS INVALID TAG 1ee7d000 (malloc_usable_size) 359 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 360 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 361 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 362 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 363 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 364 365This indicates that a function (malloc\_usable\_size) was called with 366a pointer that is either not allocated memory, or that the memory of 367the pointer has been corrupted. 368 369As with the other error message, the function in parenthesis is the 370function that was called with the bad pointer. 371 372Examples 373======== 374Enable backtrace tracking of all allocation for all processes: 375 376 adb shell stop 377 adb shell setprop libc.debug.malloc.options backtrace 378 adb shell start 379 380Enable backtrace tracking for a specific process (ls): 381 382 adb shell setprop libc.debug.malloc.options backtrace 383 adb shell setprop libc.debug.malloc.program ls 384 adb shell ls 385 386Enable backtrace tracking for the zygote and zygote based processes: 387 388 adb shell stop 389 adb shell setprop libc.debug.malloc.program app_process 390 adb shell setprop libc.debug.malloc.options backtrace 391 adb shell start 392 393Enable multiple options (backtrace and guards): 394 395 adb shell stop 396 adb shell setprop libc.debug.malloc.options "\"backtrace guards\"" 397 adb shell start 398 399Enable malloc debug when multiple processes have the same name. This method 400can be used to enable malloc debug for only a very specific process if 401multiple processes have the same name. 402 403Note: The double quotes in the adb shell command are necessary. Otherwise, 404the setprop command will fail since the backtrace guards options will look 405like two arguments instead of one. 406 407 adb shell 408 # setprop libc.debug.malloc.env_enabled 409 # setprop libc.debug.malloc.options backtrace 410 # export LIBC_DEBUG_MALLOC_ENABLE 1 411 # ls 412 413Enable malloc debug and dump the native allocation with backtraces to 414a file. This only works for zygote based java processes. 415 416 adb shell stop 417 adb shell setprop libc.debug.malloc.options backtrace 418 adb shell start 419 adb shell am dumpheap -n <PID_TO_DUMP> /data/local/tmp/heap.txt 420 421It is possible to use the backtrace\_enable\_on\_signal option as well, 422but it must be enabled through the signal before the file will contain 423any data. 424