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. (See the "Examples" section.) 9 10The documentation for malloc debug on older versions of Android is 11[here](README_marshmallow_and_earlier.md). 12 13When malloc debug is enabled, it works by adding a shim layer that replaces 14the normal allocation calls. The replaced calls are: 15 16* `malloc` 17* `free` 18* `calloc` 19* `realloc` 20* `posix_memalign` 21* `memalign` 22* `aligned_alloc` 23* `malloc_usable_size` 24 25On 32 bit systems, these two deprecated functions are also replaced: 26 27* `pvalloc` 28* `valloc` 29 30Any errors detected by the library are reported in the log. 31 32NOTE: There is a small behavioral change beginning in P for realloc. 33Before, a realloc from one size to a smaller size would not update the 34backtrace related to the allocation. Starting in P, every single realloc 35call changes the backtrace for the pointer no matter whether the pointer 36returned has changed or not. 37 38 39Controlling Malloc Debug Behavior 40--------------------------------- 41Malloc debug is controlled by individual options. Each option can be enabled 42individually, or in a group of other options. Every single option can be 43combined with every other option. 44 45Option Descriptions 46------------------- 47### front\_guard[=SIZE\_BYTES] 48Enables a small buffer placed before the allocated data. This is an attempt 49to find memory corruption occuring to a region before the original allocation. 50On first allocation, this front guard is written with a specific pattern (0xaa). 51When the allocation is freed, the guard is checked to verify it has not been 52modified. If any part of the front guard is modified, an error will be reported 53in the log indicating what bytes changed. 54 55If the backtrace option is also enabled, then any error message will include 56the backtrace of the allocation site. 57 58If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 59The default is 32 bytes, the max bytes is 16384. SIZE\_BYTES will be 60padded so that it is a multiple of 8 bytes on 32 bit systems and 16 bytes 61on 64 bit systems to make sure that the allocation returned is aligned 62properly. 63 64This option adds a special header to all allocations that contains the guard 65and information about the original allocation. 66 67Example error: 68 69 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED FRONT GUARD 70 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-32] = 0x00 (expected 0xaa) 71 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[-15] = 0x02 (expected 0xaa) 72 73### rear\_guard[=SIZE\_BYTES] 74Enables a small buffer placed after the allocated data. This is an attempt 75to find memory corruption occuring to a region after the original allocation. 76On first allocation, this rear guard is written with a specific pattern (0xbb). 77When the allocation is freed, the guard is checked to verify it has not been 78modified. If any part of the rear guard is modified, an error will be reported 79in the log indicating what bytes changed. 80 81If SIZE\_BYTES is present, it indicates the number of bytes in the guard. 82The default is 32 bytes, the max bytes is 16384. 83 84This option adds a special header to all allocations that contains 85information about the original allocation. 86 87Example error: 88 89 04-10 12:00:45.621 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 SIZE 100 HAS A CORRUPTED REAR GUARD 90 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[130] = 0xbf (expected 0xbb) 91 04-10 12:00:45.622 7412 7412 E malloc_debug: allocation[131] = 0x00 (expected 0xbb) 92 93### guard[=SIZE\_BYTES] 94Enables both a front guard and a rear guard on all allocations. 95 96If SIZE\_BYTES is present, it indicates the number of bytes in both guards. 97The default is 32 bytes, the max bytes is 16384. 98 99### backtrace[=MAX\_FRAMES] 100Enable capturing the backtrace of each allocation site. 101This option will slow down allocations by an order of magnitude. If the 102system runs too slowly with this option enabled, decreasing the maximum number 103of frames captured will speed the allocations up. 104 105Note that any backtrace frames that occur within the malloc backtrace library 106itself are not recorded. 107 108If MAX\_FRAMES is present, it indicates the maximum number of frames to 109capture in a backtrace. The default is 16 frames, the maximumum value 110this can be set to is 256. 111 112Before P, this option adds a special header to all allocations that contains 113the backtrace and information about the original allocation. After that, this 114option will not add a special header. 115 116As of P, this option will also enable dumping backtrace heap data to a 117file when the process receives the signal SIGRTMAX - 17 ( which is 47 on 118Android devices). The format of this dumped data is the same format as 119that dumped when running am dumpheap -n. The default is to dump this data 120to the file /data/local/tmp/backtrace\_heap.**PID**.txt. This is useful when 121used with native only executables that run for a while since these processes 122are not spawned from a zygote process. 123 124Note that when the signal is received, the heap is not dumped until the next 125malloc/free occurs. 126 127### backtrace\_enable\_on\_signal[=MAX\_FRAMES] 128Enable capturing the backtrace of each allocation site. If the 129backtrace capture is toggled when the process receives the signal 130SIGRTMAX - 19 (which is 45 on Android devices). When this 131option is used alone, backtrace capture starts out disabled until the signal 132is received. If both this option and the backtrace option are set, then 133backtrace capture is enabled until the signal is received. 134 135If MAX\_FRAMES is present, it indicates the maximum number of frames to 136capture in a backtrace. The default is 16 frames, the maximumum value 137this can be set to is 256. 138 139Before P, this option adds a special header to all allocations that contains 140the backtrace and information about the original allocation. After that, this 141option will not add a special header. 142 143### backtrace\_dump\_on\_exit 144As of P, when the backtrace option has been enabled, this causes the backtrace 145dump heap data to be dumped to a file when the program exits. If the backtrace 146option has not been enabled, this does nothing. The default is to dump this 147to the file named /data/local/tmp/backtrace\_heap.**PID**.exit.txt. 148 149The file location can be changed by setting the backtrace\_dump\_prefix 150option. 151 152### backtrace\_dump\_prefix 153As of P, when one of the backtrace options has been enabled, this sets the 154prefix used for dumping files when the signal SIGRTMAX - 17 is received or when 155the program exits and backtrace\_dump\_on\_exit is set. 156 157The default is /data/local/tmp/backtrace\_heap. 158 159When this value is changed from the default, then the filename chosen 160on the signal will be backtrace\_dump\_prefix.**PID**.txt. The filename chosen 161when the program exits will be backtrace\_dump\_prefix.**PID**.exit.txt. 162 163### backtrace\_min\_size=ALLOCATION\_SIZE\_BYTES 164As of U, setting this in combination with the backtrace option means 165that only allocations of a size greater than or equal to 166**ALLOCATION\_SIZE\_BYTES** will be backtraced. When used in combination 167with the backtrace\_max\_size option, then allocations greater than or 168equal to backtrace\_min\_size and less than or equal to 169backtrace\_max\_size will be backtraced. The backtrace\_size option 170overrides this option, and should not be used at the same time. 171 172This option can also be used in combination with other tools such 173as [libmemunreachable](https://android.googlesource.com/platform/system/memory/libmemunreachable/+/master/README.md) 174to only get backtraces for sizes of allocations listed as being leaked. 175 176### backtrace\_max\_size=ALLOCATION\_SIZE\_BYTES 177As of U, setting this in combination with the backtrace option means 178that only allocations of a size less than or equal to 179**ALLOCATION\_SIZE\_BYTES** will be backtraced. When used in combination 180with the backtrace\_min\_size option, then allocations greater than or 181equal to backtrace\_min\_size and less than or equal to 182backtrace\_max\_size will be backtraced. The backtrace\_size option 183overrides this option, and should not be used at the same time. 184 185This option can also be used in combination with other tools such 186as [libmemunreachable](https://android.googlesource.com/platform/system/memory/libmemunreachable/+/master/README.md) 187to only get backtraces for sizes of allocations listed as being leaked. 188 189### backtrace\_size=ALLOCATION\_SIZE\_BYTES 190As of U, setting this in combination with the backtrace option means 191that only allocations of size **ALLOCATION\_SIZE\_BYTES** will be backtraced. 192This option overrides the backtrace\_min\_size and the backtrace\_max\_size. 193 194This option can also be used in combination with other tools such 195as [libmemunreachable](https://android.googlesource.com/platform/system/memory/libmemunreachable/+/master/README.md) 196to only get backtraces for sizes of allocations listed as being leaked. 197 198### backtrace\_full 199As of Q, any time that a backtrace is gathered, a different algorithm is used 200that is extra thorough and can unwind through Java frames. This will run 201slower than the normal backtracing function. 202 203### bt, bt\_dmp\_on\_ex, bt\_dmp\_pre, bt\_en\_on\_sig, bt\_full, bt\_max\_sz, bt\_min\_sz, bt\_sz 204As of U, add shorter aliases for backtrace related options to avoid property length restrictions. 205 206| Alias | Option | 207|:----------------|:------------------------------| 208| bt | backtrace | 209| bt\_dmp\_on\_ex | backtrace\_dump\_on\_exit | 210| bt\_dmp\_pre | backtrace\_dump\_prefix | 211| bt\_en\_on\_sig | backtrace\_enable\_on\_signal | 212| bt\_full | backtrace\_full | 213| bt\_max\_sz | backtrace\_max\_size | 214| bt\_min\_sz | backtrace\_min\_size | 215| bt\_sz | backtrace\_size | 216 217### check\_unreachable\_on\_signal 218As of Android U, this option will trigger a check for unreachable memory 219in a process. Specifically, if the signal SIGRTMAX - 16 (which is 48 on 220Android devices). The best way to see the exact signal being used is to 221enable the verbose option then look at the log for the message: 222 223 Run: 'kill -48 <PID>' to check for unreachable memory. 224 225When the signal is received, the actual unreachable check only triggers 226on the next allocation that happens in the process (malloc/free, etc). 227 228If a process is not doing any allocations, it can be forced to trigger when 229running: 230 231 debuggerd -b <PID> 232 233**NOTE**: The unreachable check can fail for protected processes, so it 234might be necessary to run: 235 236 setenforce 0 237 238To get the unreachable data. 239 240### fill\_on\_alloc[=MAX\_FILLED\_BYTES] 241Any allocation routine, other than calloc, will result in the allocation being 242filled with the value 0xeb. When doing a realloc to a larger size, the bytes 243above the original usable size will be set to 0xeb. 244 245If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 246of bytes in the allocation. The default is to fill the entire allocation. 247 248### fill\_on\_free[=MAX\_FILLED\_BYTES] 249When an allocation is freed, fill it with 0xef. 250 251If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 252of bytes in the allocation. The default is to fill the entire allocation. 253 254### fill[=MAX\_FILLED\_BYTES] 255This enables both the fill\_on\_alloc option and the fill\_on\_free option. 256 257If MAX\_FILLED\_BYTES is present, it will only fill up to the specified number 258of bytes in the allocation. The default is to fill the entire allocation. 259 260### expand\_alloc[=EXPAND\_BYTES] 261Add an extra amount to allocate for every allocation. 262 263If XX is present, it is the number of bytes to expand the allocation by. 264The default is 16 bytes, the max bytes is 16384. 265 266### free\_track[=ALLOCATION\_COUNT] 267When a pointer is freed, do not free the memory right away, but add it to 268a list of freed allocations. In addition to being added to the list, the 269entire allocation is filled with the value 0xef, and the backtrace at 270the time of the free is recorded. The backtrace recording is completely 271separate from the backtrace option, and happens automatically if this 272option is enabled. By default, a maximum of 16 frames will be recorded, 273but this value can be changed using the free\_track\_backtrace\_num\_frames 274option. It can also be completely disabled by setting the option to zero. 275See the full description of this option below. 276 277When the list is full, an allocation is removed from the list and is 278checked to make sure that none of the contents have been modified since 279being placed on the list. When the program terminates, all of the allocations 280left on the list are verified. 281 282If ALLOCATION\_COUNT is present, it indicates the total number of allocations 283in the list. The default is to record 100 freed allocations, the max 284allocations to record is 16384. 285 286Before P, this option adds a special header to all allocations that contains 287the backtrace and information about the original allocation. After that, this 288option will not add a special header. 289 290Example error: 291 292 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE 293 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[20] = 0xaf (expected 0xef) 294 04-15 12:00:31.305 7412 7412 E malloc_debug: allocation[99] = 0x12 (expected 0xef) 295 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of free: 296 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 297 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 298 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 299 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 300 301In addition, there is another type of error message that can occur if 302an allocation has a special header applied, and the header is corrupted 303before the verification occurs. This is the error message that will be found 304in the log: 305 306 04-15 12:00:31.604 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS CORRUPTED HEADER TAG 0x1cc7dc00 AFTER FREE 307 308### free\_track\_backtrace\_num\_frames[=MAX\_FRAMES] 309This option only has meaning if free\_track is set. It indicates how many 310backtrace frames to capture when an allocation is freed. 311 312If MAX\_FRAMES is present, it indicates the number of frames to capture. 313If the value is set to zero, then no backtrace will be captured when the 314allocation is freed. The default is to record 16 frames, the max number of 315frames to to record is 256. 316 317### leak\_track 318Track all live allocations. When the program terminates, all of the live 319allocations will be dumped to the log. If the backtrace option was enabled, 320then the log will include the backtrace of the leaked allocations. This 321option is not useful when enabled globally because a lot of programs do not 322free everything before the program terminates. 323 324Before P, this option adds a special header to all allocations that contains 325the backtrace and information about the original allocation. After that, this 326option will not add a special header. 327 328Example leak error found in the log: 329 330 04-15 12:35:33.304 7412 7412 E malloc_debug: +++ APP leaked block of size 100 at 0x2be3b0b0 (leak 1 of 2) 331 04-15 12:35:33.304 7412 7412 E malloc_debug: Backtrace at time of allocation: 332 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 333 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 334 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 335 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 336 04-15 12:35:33.305 7412 7412 E malloc_debug: +++ APP leaked block of size 24 at 0x7be32380 (leak 2 of 2) 337 04-15 12:35:33.305 7412 7412 E malloc_debug: Backtrace at time of allocation: 338 04-15 12:35:33.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 339 04-15 12:35:33.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 340 04-15 12:35:33.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 341 04-15 12:35:33.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 342 343### record\_allocs[=TOTAL\_ENTRIES] 344Keep track of every allocation/free made on every thread and dump them 345to a file when the signal SIGRTMAX - 18 (which is 46 on Android devices) 346is received. 347 348If TOTAL\_ENTRIES is set, then it indicates the total number of 349allocation/free records that can be retained. If the number of records 350reaches the TOTAL\_ENTRIES value, then any further allocations/frees are 351not recorded. The default value is 8,000,000 and the maximum value this 352can be set to is 50,000,000. 353 354Once the signal is received, and the current records are written to the 355file, all current records are deleted. Any allocations/frees occuring while 356the data is being dumped to the file are ignored. 357 358**NOTE**: This option is not available until the O release of Android. 359 360The allocation data is written in a human readable format. Every line begins 361with the THREAD\_ID returned by gettid(), which is the thread that is making 362the allocation/free. If a new thread is created, no special line is added 363to the file. However, when a thread completes, a special entry is added to 364the file indicating this. 365 366The thread complete line is: 367 368**THREAD\_ID**: thread\_done 0x0 369 370Example: 371 372 187: thread_done 0x0 373 374Below is how each type of allocation/free call ends up in the file dump. 375 376pointer = malloc(size) 377 378**THREAD\_ID**: malloc pointer size 379 380Example: 381 382 186: malloc 0xb6038060 20 383 384free(pointer) 385 386**THREAD\_ID**: free pointer 387 388Example: 389 390 186: free 0xb6038060 391 392pointer = calloc(nmemb, size) 393 394**THREAD\_ID**: calloc pointer nmemb size 395 396Example: 397 398 186: calloc 0xb609f080 32 4 399 400new\_pointer = realloc(old\_pointer, size) 401 402**THREAD\_ID**: realloc new\_pointer old\_pointer size 403 404Example: 405 406 186: realloc 0xb609f080 0xb603e9a0 12 407 408pointer = memalign(alignment, size) 409 410**THREAD\_ID**: memalign pointer alignment size 411 412pointer = aligned\_alloc(alignment, size) 413 414**THREAD\_ID**: memalign pointer alignment size 415 416posix\_memalign(&pointer, alignment, size) 417 418**THREAD\_ID**: memalign pointer alignment size 419 420Example: 421 422 186: memalign 0x85423660 16 104 423 424pointer = valloc(size) 425 426**THREAD\_ID**: memalign pointer 4096 size 427 428Example: 429 430 186: memalign 0x85423660 4096 112 431 432pointer = pvalloc(size) 433 434**THREAD\_ID**: memalign pointer 4096 <b>SIZE\_ROUNDED\_UP\_TO\_4096</b> 435 436Example: 437 438 186: memalign 0x85423660 4096 8192 439 440### record\_allocs\_file[=FILE\_NAME] 441This option only has meaning if record\_allocs is set. It indicates the 442file where the recorded allocations will be found. 443 444If FILE\_NAME is set, then it indicates where the record allocation data 445will be placed. 446 447**NOTE**: This option is not available until the O release of Android. 448 449### verify\_pointers 450Track all live allocations to determine if a pointer is used that does not 451exist. This option is a lightweight way to verify that all 452free/malloc\_usable\_size/realloc calls are passed valid pointers. 453 454Example error: 455 456 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 UNKNOWN POINTER (free) 457 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 458 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 459 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 460 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 461 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 462 463Where the name of the function varies depending on the function that called 464with a bad pointer. Only three functions do this checking: free, 465malloc\_usable\_size, realloc. 466 467**NOTE**: This option is not available until the P release of Android. 468 469### abort\_on\_error 470When malloc debug detects an error, abort after sending the error 471log message. 472 473**NOTE**: If leak\_track is enabled, no abort occurs if leaks have been 474detected when the process is exiting. 475 476### verbose 477As of Android Q, all info messages will be turned off by default. For example, 478in Android P and older, enabling malloc debug would result in this message 479in the log: 480 481 08-16 15:54:16.060 26947 26947 I libc : /system/bin/app_process64: malloc debug enabled 482 483In android Q, this message will not be displayed because these info messages 484slow down process start up. However, if you want to re-enable these messages, 485add the verbose option. All of the "Run XXX" messages are also silenced unless 486the verbose option is specified. This is an example of the type 487of messages that are no longer displayed: 488 489 09-10 01:03:50.070 557 557 I malloc_debug: /system/bin/audioserver: Run: 'kill -47 557' to dump the backtrace. 490 491Additional Errors 492----------------- 493There are a few other error messages that might appear in the log. 494 495### Use After Free 496 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (free) 497 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace of original free: 498 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 499 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 500 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 501 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 502 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 503 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 504 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 505 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 506 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 507 508This indicates that code is attempting to free an already freed pointer. The 509name in parenthesis indicates that the application called the function 510*free* with the bad pointer. 511 512For example, this message: 513 514 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (realloc) 515 516Would indicate that the application called the *realloc* function 517with an already freed pointer. 518 519### Invalid Tag 520 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS INVALID TAG 1ee7d000 (malloc_usable_size) 521 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 522 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 523 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 524 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 525 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 526 527This indicates that a function (malloc\_usable\_size) was called with 528a pointer that is either not allocated memory, or that the memory of 529the pointer has been corrupted. 530 531As with the other error message, the function in parenthesis is the 532function that was called with the bad pointer. 533 534Backtrace Heap Dump Format 535========================== 536 537This section describes the format of the backtrace heap dump. This data is 538generated by am dumpheap -n or, as of P, by the signal or on exit. 539 540The data has this header: 541 542 Android Native Heap Dump v1.0 543 544 Total memory: XXXX 545 Allocation records: YYYY 546 Backtrace size: ZZZZ 547 548Total memory is the total of all of the currently live allocations. 549Allocation records is the total number of allocation records. 550Backtrace size is the maximum number of backtrace frames that can be present. 551 552Following this header are two different sections, the first section is the 553allocation records, the second section is the map data. 554 555The allocation record data has this format: 556 557 z ZYGOTE_CHILD_ALLOC sz ALLOCATION_SIZE num NUM_ALLOCATIONS bt FRAMES 558 559ZYGOTE\_CHILD\_ALLOC is either 0 or 1. 0 means this was allocated by the 560zygote process or in a process not spawned from the zygote. 1 means this 561was allocated by an application after it forked off from the zygote process. 562 563ALLOCATION\_SIZE is the size of the allocation. 564NUM\_ALLOCATIONS is the number of allocations that have this size and have the 565same backtrace. 566FRAMES is a list of instruction pointers that represent the backtrace of the 567allocation. 568 569Example: 570 571 z 0 sz 400 num 1 bt 0000a230 0000b500 572 z 1 sz 500 num 3 bt 0000b000 0000c000 573 574The first allocation record was created by the zygote of size 400 only one 575with this backtrace/size and a backtrace of 0xa230, 0xb500. 576The second allocation record was create by an application spawned from the 577zygote of size 500, where there are three of these allocation with the same 578backtrace/size and a backtrace of 0xb000, 0xc000. 579 580The final section is the map data for the process: 581 582 MAPS 583 7fe9181000-7fe91a2000 rw-p 00000000 00:00 0 /system/lib/libc.so 584 . 585 . 586 . 587 END 588 589The map data is simply the output of /proc/PID/maps. This data can be used to 590decode the frames in the backtraces. 591 592There are now multiple versions of the file: 593 594Android P produces version v1.1 of the heap dump. 595 596 Android Native Heap Dump v1.1 597 598The only difference between v1.0 and v1.1 is that the NUM\_ALLOCATIONS 599value is always accurate in v1.1. A previous version of malloc debug set 600NUM\_ALLOCATIONS to an incorrect value. For heap dump v1.0, the 601NUM\_ALLOCATIONS value should be treated as always 1 no matter what is 602actually present. 603 604Android Q introduces v1.2 of the heap dump. The new header looks like this: 605 606 Android Native Heap Dump v1.2 607 608 Build fingerprint: 'google/taimen/taimen:8.1.0/OPM2.171026.006.C1/4769658:user/release-keys' 609 610The new line fingerprint line is the contents of the ro.build.fingerprint 611property. 612 613The new version no longer 0 pads the backtrace addresses. In v1.0/v1.1: 614 615 z 0 sz 400 num 1 bt 0000a230 0000b500 616 617While v1.2: 618 619 z 0 sz 400 num 1 bt a230 b500 620 621In addition, when the new option backtrace\_full is used, another line will 622be added to every backtrace line. The line will be: 623 624 bt_info {"MAP_NAME" RELATIVE_TO_MAP_PC "FUNCTION_NAME" FUNCTION_OFFSET} ... 625 626For each backtrace pc, there will be one element in braces. 627 628MAP\_NAME is the name of the map in which the backtrace pc exists. If there is 629no valid map name, this will be empty. 630RELATIVE\_TO\_MAP\_PC is the hexadecimal value of the relative pc to the map. 631FUNCTION\_NAME the name of the function for this pc. If there is no valid 632function name, then it will be empty. 633FUNCTION\_OFFSET the hexadecimal offset from the beginning of the function. If 634the FUNCTION\_NAME is empty, then this value will always be zero. 635 636An example of this new format: 637 638 z 0 sz 400 num 1 bt a2a0 b510 639 bt_info {"/system/libc.so" 2a0 "abort" 24} {"/system/libutils.so" 510 "" 0} 640 641In this example, the first backtrace frame has a pc of 0xa2a0 and is in the 642map named /system/libc.so which starts at 0xa000. The relative pc is 0x2a0, 643and it is in the function abort + 0x24. 644The second backtrace frame has a pc of 0xb510 and is in the map named 645/system/libutils.so which starts at 0xb000. The relative pc is 0x510 and 646it is in an unknown function. 647 648Examples 649======== 650 651### For platform developers 652 653Enable backtrace tracking of all allocation for all processes: 654 655 adb shell stop 656 adb shell setprop libc.debug.malloc.options backtrace 657 adb shell start 658 659Enable backtrace tracking for a specific process (ls): 660 661 adb shell setprop libc.debug.malloc.options backtrace 662 adb shell setprop libc.debug.malloc.program ls 663 adb shell ls 664 665Enable backtrace tracking for the zygote and zygote based processes: 666 667 adb shell stop 668 adb shell setprop libc.debug.malloc.program app_process 669 adb shell setprop libc.debug.malloc.options backtrace 670 adb shell start 671 672Enable multiple options (backtrace and guard): 673 674 adb shell stop 675 adb shell setprop libc.debug.malloc.options "\"backtrace guard\"" 676 adb shell start 677 678Note: The two levels of quoting in the adb shell command is necessary. 679The outer layer of quoting is for the shell on the host, to ensure that the 680inner layer of quoting is sent to the device, to make 'backtrace guard' 681a single argument. 682 683Enable malloc debug using an environment variable (pre-O Android release): 684 685 adb shell 686 # setprop libc.debug.malloc.env_enabled 1 687 # setprop libc.debug.malloc.options backtrace 688 # export LIBC_DEBUG_MALLOC_ENABLE=1 689 # ls 690 691Enable malloc debug using an environment variable (Android O or later): 692 693 adb shell 694 # export LIBC_DEBUG_MALLOC_OPTIONS=backtrace 695 # ls 696 697Any process spawned from this shell will run with malloc debug enabled 698using the backtrace option. 699 700 adb shell stop 701 adb shell setprop libc.debug.malloc.options backtrace 702 adb shell start 703 adb shell am dumpheap -n <PID_TO_DUMP> /data/local/tmp/heap.txt 704 705It is possible to use the backtrace\_enable\_on\_signal option as well, 706but, obviously, it must be enabled through the signal before the file will 707contain any data. 708 709### For app developers 710 711App developers should check the NDK documentation about 712[wrap.sh](https://developer.android.com/ndk/guides/wrap-script.html) 713for the best way to use malloc debug in Android O or later on non-rooted 714devices. 715 716**NOTE**: Android 12 introduced a bug that can cause the wrap.\<APP\> property to 717no longer work. Use the commands below so that the wrap.\<APP\> instructions will work: 718 719 adb shell setprop dalvik.vm.force-java-zygote-fork-loop true 720 adb shell stop 721 adb shell start 722 723If you do have a rooted device, you can enable malloc debug for a specific 724program/application (Android O or later): 725 726 adb shell setprop wrap.<APP> '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace logwrapper"' 727 728If you need to enable multiple options using this method, then you can set 729them like so: 730 731 adb shell setprop wrap.<APP> '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace\ leak_track\ fill logwrapper"' 732 733For example, to enable malloc debug for the google search box (Android O or later): 734 735 adb shell setprop wrap.com.google.android.googlequicksearchbox '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace logwrapper"' 736 adb shell am force-stop com.google.android.googlequicksearchbox 737 738If you are setting multiple options and the app does not appear to start 739properly, check the logcat looking for this message 740(`adb logcat -d | grep "malloc debug"`): 741 742 08-16 15:54:16.060 26947 26947 I libc : /system/bin/app_process64: malloc debug enabled 743 744If you do not see this message, then the wrap property was not set correctly. 745Run: 746 747 adb shell getprop | grep wrap 748 749And verify that any spaces are properly escaped. 750 751NOTE: On pre-O versions of the Android OS, property names had a length limit 752of 32. This meant that to create a wrap property with the name of the app, it 753was necessary to truncate the name to fit. On O, property names can be 754an order of magnitude larger, so there should be no need to truncate the name 755at all. 756 757To detect leaks while an app is running: 758 759 adb shell dumpsys meminfo --unreachable <PID_OF_APP> 760 761Without also enabling malloc debug, this command will only tell 762you whether it can detect leaked memory, not where those leaks are 763occurring. If you enable malloc debug with the backtrace option for your 764app before running the dumpsys command, you'll get backtraces showing 765where the memory was allocated. 766 767For backtraces from your app to be useful, you'll want to keep the 768symbols in your app's shared libraries rather than stripping them. That 769way you'll see the location of the leak directly without having to use 770something like the <code>ndk-stack</code> tool. 771