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