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/+/main/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/+/main/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/+/main/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### log\_allocator\_stats\_on\_signal 344As of Android V, this option will trigger a call to: 345 346 mallopt(M_LOG_STATS, 0); 347 348When a process receives the signal SIGRTMAX - 15 (which is 49 on Android 349devices). The mallopt call is not async safe and is not called from the 350signal handler directly. Instead, the next time any allocation call occurs, 351the mallopt is called. 352 353### record\_allocs[=TOTAL\_ENTRIES] 354Keep track of every allocation/free made on every thread and dump them 355to a file when the signal SIGRTMAX - 18 (which is 46 on Android devices) 356is received. 357 358If TOTAL\_ENTRIES is set, then it indicates the total number of 359allocation/free records that can be retained. If the number of records 360reaches the TOTAL\_ENTRIES value, then any further allocations/frees are 361not recorded. The default value is 8,000,000 and the maximum value this 362can be set to is 50,000,000. 363 364Once the signal is received, and the current records are written to the 365file, all current records are deleted. Any allocations/frees occuring while 366the data is being dumped to the file are ignored. 367 368**NOTE**: This option is not available until the O release of Android. 369 370The allocation data is written in a human readable format. Every line begins 371with the THREAD\_ID returned by gettid(), which is the thread that is making 372the allocation/free. If a new thread is created, no special line is added 373to the file. However, when a thread completes, a special entry is added to 374the file indicating this. 375 376The thread complete line is: 377 378**THREAD\_ID**: thread\_done 0x0 379 380Example: 381 382 187: thread_done 0x0 383 384Below is how each type of allocation/free call ends up in the file dump. 385 386pointer = malloc(size) 387 388**THREAD\_ID**: malloc pointer size 389 390Example: 391 392 186: malloc 0xb6038060 20 393 394free(pointer) 395 396**THREAD\_ID**: free pointer 397 398Example: 399 400 186: free 0xb6038060 401 402pointer = calloc(nmemb, size) 403 404**THREAD\_ID**: calloc pointer nmemb size 405 406Example: 407 408 186: calloc 0xb609f080 32 4 409 410new\_pointer = realloc(old\_pointer, size) 411 412**THREAD\_ID**: realloc new\_pointer old\_pointer size 413 414Example: 415 416 186: realloc 0xb609f080 0xb603e9a0 12 417 418pointer = memalign(alignment, size) 419 420**THREAD\_ID**: memalign pointer alignment size 421 422pointer = aligned\_alloc(alignment, size) 423 424**THREAD\_ID**: memalign pointer alignment size 425 426posix\_memalign(&pointer, alignment, size) 427 428**THREAD\_ID**: memalign pointer alignment size 429 430Example: 431 432 186: memalign 0x85423660 16 104 433 434pointer = valloc(size) 435 436**THREAD\_ID**: memalign pointer 4096 size 437 438Example: 439 440 186: memalign 0x85423660 4096 112 441 442pointer = pvalloc(size) 443 444**THREAD\_ID**: memalign pointer 4096 <b>SIZE\_ROUNDED\_UP\_TO\_4096</b> 445 446Example: 447 448 186: memalign 0x85423660 4096 8192 449 450### record\_allocs\_file[=FILE\_NAME] 451This option only has meaning if record\_allocs is set. It indicates the 452file where the recorded allocations will be found. 453 454If FILE\_NAME is set, then it indicates where the record allocation data 455will be placed. 456 457**NOTE**: This option is not available until the O release of Android. 458 459### verify\_pointers 460Track all live allocations to determine if a pointer is used that does not 461exist. This option is a lightweight way to verify that all 462free/malloc\_usable\_size/realloc calls are passed valid pointers. 463 464Example error: 465 466 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 UNKNOWN POINTER (free) 467 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 468 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 469 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 470 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 471 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 472 473Where the name of the function varies depending on the function that called 474with a bad pointer. Only three functions do this checking: free, 475malloc\_usable\_size, realloc. 476 477**NOTE**: This option is not available until the P release of Android. 478 479### abort\_on\_error 480When malloc debug detects an error, abort after sending the error 481log message. 482 483**NOTE**: If leak\_track is enabled, no abort occurs if leaks have been 484detected when the process is exiting. 485 486### verbose 487As of Android Q, all info messages will be turned off by default. For example, 488in Android P and older, enabling malloc debug would result in this message 489in the log: 490 491 08-16 15:54:16.060 26947 26947 I libc : /system/bin/app_process64: malloc debug enabled 492 493In android Q, this message will not be displayed because these info messages 494slow down process start up. However, if you want to re-enable these messages, 495add the verbose option. All of the "Run XXX" messages are also silenced unless 496the verbose option is specified. This is an example of the type 497of messages that are no longer displayed: 498 499 09-10 01:03:50.070 557 557 I malloc_debug: /system/bin/audioserver: Run: 'kill -47 557' to dump the backtrace. 500 501Additional Errors 502----------------- 503There are a few other error messages that might appear in the log. 504 505### Use After Free 506 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (free) 507 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace of original free: 508 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 509 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 510 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 511 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 512 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 513 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 514 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 515 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 516 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 517 518This indicates that code is attempting to free an already freed pointer. The 519name in parenthesis indicates that the application called the function 520*free* with the bad pointer. 521 522For example, this message: 523 524 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 USED AFTER FREE (realloc) 525 526Would indicate that the application called the *realloc* function 527with an already freed pointer. 528 529### Invalid Tag 530 04-15 12:00:31.304 7412 7412 E malloc_debug: +++ ALLOCATION 0x12345678 HAS INVALID TAG 1ee7d000 (malloc_usable_size) 531 04-15 12:00:31.305 7412 7412 E malloc_debug: Backtrace at time of failure: 532 04-15 12:00:31.305 7412 7412 E malloc_debug: #00 pc 00029310 /system/lib/libc.so 533 04-15 12:00:31.305 7412 7412 E malloc_debug: #01 pc 00021438 /system/lib/libc.so (newlocale+160) 534 04-15 12:00:31.305 7412 7412 E malloc_debug: #02 pc 000a9e38 /system/lib/libc++.so 535 04-15 12:00:31.305 7412 7412 E malloc_debug: #03 pc 000a28a8 /system/lib/libc++.so 536 537This indicates that a function (malloc\_usable\_size) was called with 538a pointer that is either not allocated memory, or that the memory of 539the pointer has been corrupted. 540 541As with the other error message, the function in parenthesis is the 542function that was called with the bad pointer. 543 544Backtrace Heap Dump Format 545========================== 546 547This section describes the format of the backtrace heap dump. This data is 548generated by am dumpheap -n or, as of P, by the signal or on exit. 549 550The data has this header: 551 552 Android Native Heap Dump v1.0 553 554 Total memory: XXXX 555 Allocation records: YYYY 556 Backtrace size: ZZZZ 557 558Total memory is the total of all of the currently live allocations. 559Allocation records is the total number of allocation records. 560Backtrace size is the maximum number of backtrace frames that can be present. 561 562Following this header are two different sections, the first section is the 563allocation records, the second section is the map data. 564 565The allocation record data has this format: 566 567 z ZYGOTE_CHILD_ALLOC sz ALLOCATION_SIZE num NUM_ALLOCATIONS bt FRAMES 568 569ZYGOTE\_CHILD\_ALLOC is either 0 or 1. 0 means this was allocated by the 570zygote process or in a process not spawned from the zygote. 1 means this 571was allocated by an application after it forked off from the zygote process. 572 573ALLOCATION\_SIZE is the size of the allocation. 574NUM\_ALLOCATIONS is the number of allocations that have this size and have the 575same backtrace. 576FRAMES is a list of instruction pointers that represent the backtrace of the 577allocation. 578 579Example: 580 581 z 0 sz 400 num 1 bt 0000a230 0000b500 582 z 1 sz 500 num 3 bt 0000b000 0000c000 583 584The first allocation record was created by the zygote of size 400 only one 585with this backtrace/size and a backtrace of 0xa230, 0xb500. 586The second allocation record was create by an application spawned from the 587zygote of size 500, where there are three of these allocation with the same 588backtrace/size and a backtrace of 0xb000, 0xc000. 589 590The final section is the map data for the process: 591 592 MAPS 593 7fe9181000-7fe91a2000 rw-p 00000000 00:00 0 /system/lib/libc.so 594 . 595 . 596 . 597 END 598 599The map data is simply the output of /proc/PID/maps. This data can be used to 600decode the frames in the backtraces. 601 602There are now multiple versions of the file: 603 604Android P produces version v1.1 of the heap dump. 605 606 Android Native Heap Dump v1.1 607 608The only difference between v1.0 and v1.1 is that the NUM\_ALLOCATIONS 609value is always accurate in v1.1. A previous version of malloc debug set 610NUM\_ALLOCATIONS to an incorrect value. For heap dump v1.0, the 611NUM\_ALLOCATIONS value should be treated as always 1 no matter what is 612actually present. 613 614Android Q introduces v1.2 of the heap dump. The new header looks like this: 615 616 Android Native Heap Dump v1.2 617 618 Build fingerprint: 'google/taimen/taimen:8.1.0/OPM2.171026.006.C1/4769658:user/release-keys' 619 620The new line fingerprint line is the contents of the ro.build.fingerprint 621property. 622 623The new version no longer 0 pads the backtrace addresses. In v1.0/v1.1: 624 625 z 0 sz 400 num 1 bt 0000a230 0000b500 626 627While v1.2: 628 629 z 0 sz 400 num 1 bt a230 b500 630 631In addition, when the new option backtrace\_full is used, another line will 632be added to every backtrace line. The line will be: 633 634 bt_info {"MAP_NAME" RELATIVE_TO_MAP_PC "FUNCTION_NAME" FUNCTION_OFFSET} ... 635 636For each backtrace pc, there will be one element in braces. 637 638MAP\_NAME is the name of the map in which the backtrace pc exists. If there is 639no valid map name, this will be empty. 640RELATIVE\_TO\_MAP\_PC is the hexadecimal value of the relative pc to the map. 641FUNCTION\_NAME the name of the function for this pc. If there is no valid 642function name, then it will be empty. 643FUNCTION\_OFFSET the hexadecimal offset from the beginning of the function. If 644the FUNCTION\_NAME is empty, then this value will always be zero. 645 646An example of this new format: 647 648 z 0 sz 400 num 1 bt a2a0 b510 649 bt_info {"/system/libc.so" 2a0 "abort" 24} {"/system/libutils.so" 510 "" 0} 650 651In this example, the first backtrace frame has a pc of 0xa2a0 and is in the 652map named /system/libc.so which starts at 0xa000. The relative pc is 0x2a0, 653and it is in the function abort + 0x24. 654The second backtrace frame has a pc of 0xb510 and is in the map named 655/system/libutils.so which starts at 0xb000. The relative pc is 0x510 and 656it is in an unknown function. 657 658Examples 659======== 660 661### For platform developers 662 663Enable backtrace tracking of all allocation for all processes: 664 665 adb shell stop 666 adb shell setprop libc.debug.malloc.options backtrace 667 adb shell start 668 669Enable backtrace tracking for a specific process (ls): 670 671 adb shell setprop libc.debug.malloc.options backtrace 672 adb shell setprop libc.debug.malloc.program ls 673 adb shell ls 674 675Enable backtrace tracking for the zygote and zygote based processes: 676 677 adb shell stop 678 adb shell setprop libc.debug.malloc.program app_process 679 adb shell setprop libc.debug.malloc.options backtrace 680 adb shell start 681 682Enable multiple options (backtrace and guard): 683 684 adb shell stop 685 adb shell setprop libc.debug.malloc.options "\"backtrace guard\"" 686 adb shell start 687 688Note: The two levels of quoting in the adb shell command is necessary. 689The outer layer of quoting is for the shell on the host, to ensure that the 690inner layer of quoting is sent to the device, to make 'backtrace guard' 691a single argument. 692 693Enable malloc debug using an environment variable (pre-O Android release): 694 695 adb shell 696 # setprop libc.debug.malloc.env_enabled 1 697 # setprop libc.debug.malloc.options backtrace 698 # export LIBC_DEBUG_MALLOC_ENABLE=1 699 # ls 700 701Enable malloc debug using an environment variable (Android O or later): 702 703 adb shell 704 # export LIBC_DEBUG_MALLOC_OPTIONS=backtrace 705 # ls 706 707Any process spawned from this shell will run with malloc debug enabled 708using the backtrace option. 709 710 adb shell stop 711 adb shell setprop libc.debug.malloc.options backtrace 712 adb shell start 713 adb shell am dumpheap -n <PID_TO_DUMP> /data/local/tmp/heap.txt 714 715It is possible to use the backtrace\_enable\_on\_signal option as well, 716but, obviously, it must be enabled through the signal before the file will 717contain any data. 718 719### For app developers 720 721App developers should check the NDK documentation about 722[wrap.sh](https://developer.android.com/ndk/guides/wrap-script.html) 723for the best way to use malloc debug in Android O or later on non-rooted 724devices. 725 726**NOTE**: Android 12 introduced a bug that can cause the wrap.\<APP\> property to 727no longer work. Use the commands below so that the wrap.\<APP\> instructions will work: 728 729 adb shell setprop dalvik.vm.force-java-zygote-fork-loop true 730 adb shell stop 731 adb shell start 732 733If you do have a rooted device, you can enable malloc debug for a specific 734program/application (Android O or later): 735 736 adb shell setprop wrap.<APP> '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace logwrapper"' 737 738If you need to enable multiple options using this method, then you can set 739them like so: 740 741 adb shell setprop wrap.<APP> '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace\ leak_track\ fill logwrapper"' 742 743For example, to enable malloc debug for the google search box (Android O or later): 744 745 adb shell setprop wrap.com.google.android.googlequicksearchbox '"LIBC_DEBUG_MALLOC_OPTIONS=backtrace logwrapper"' 746 adb shell am force-stop com.google.android.googlequicksearchbox 747 748If you are setting multiple options and the app does not appear to start 749properly, check the logcat looking for this message 750(`adb logcat -d | grep "malloc debug"`): 751 752 08-16 15:54:16.060 26947 26947 I libc : /system/bin/app_process64: malloc debug enabled 753 754If you do not see this message, then the wrap property was not set correctly. 755Run: 756 757 adb shell getprop | grep wrap 758 759And verify that any spaces are properly escaped. 760 761NOTE: On pre-O versions of the Android OS, property names had a length limit 762of 32. This meant that to create a wrap property with the name of the app, it 763was necessary to truncate the name to fit. On O, property names can be 764an order of magnitude larger, so there should be no need to truncate the name 765at all. 766 767To detect leaks while an app is running: 768 769 adb shell dumpsys meminfo --unreachable <PID_OF_APP> 770 771Without also enabling malloc debug, this command will only tell 772you whether it can detect leaked memory, not where those leaks are 773occurring. If you enable malloc debug with the backtrace option for your 774app before running the dumpsys command, you'll get backtraces showing 775where the memory was allocated. 776 777For backtraces from your app to be useful, you'll want to keep the 778symbols in your app's shared libraries rather than stripping them. That 779way you'll see the location of the leak directly without having to use 780something like the <code>ndk-stack</code> tool. 781